Using with CodeIgniter4

You can find all files here:

Or here:



Architecture design

CodeIgniter4 will serve our API.

And Viewi will be responsible for rendering HTML pages on the client-side as a front-end application. But also it will be responsible for rendering HTML on the server-side (SSR). In both cases, Viewi application can consume the server's API using HttpClient:

  • In the browser - AJAX
  • During SSR - simulate a request and pass it to the CodeIgniter4 application (direct invocation)

(CodeIgniter4 - API) <-- data --> (Viewi application)

Basic idea

Viewi is capable of handling routes on its own, so the simplest solution here is to assign Viewi handler to a 404 CodeIgniter route:



Couple of important settings to consider here.

To run Viewi application you need to tell Viewi where to put its compiled files. It should be a public folder.

In this case, it is a public folder:

__DIR__ . '/../public/'

Public url path to resolve assets, in this case it's an empty string '' (means assets base URL is http://localhost/)

NPM watch setting, you can either use it, or you can disable it.

->watchWithNPM(true) or ->watchWithNPM(false)

Setting it to false will trigger a build process on the first request.

The final config should look something like this:



use Viewi\AppConfig;

$viewiAppPath = __DIR__ . $d;
$componentsPath =  $viewiAppPath . 'Components';
$buildPath = $viewiAppPath . 'build';
$jsPath = $viewiAppPath . 'js';
$assetsSourcePath = $viewiAppPath . 'assets';
$publicPath = __DIR__ . $d . '..' . $d . '..' . $d . 'public';
$assetsPublicUrl = '';

return (new AppConfig('ci4'))


Viewi application is located here: app\ViewiApp

Viewi bridge and handler files are located here: app\ViewiBridge

Extend the Response

In order to supply Viewi with original typed data that CodeIgniter4 returns from the API, we need to preserve that data in the response.

Typical Response class converts your data into a JSON string that will not satisfy our Viewi application.

Let's extend it


namespace App\ViewiBridge;

use CodeIgniter\HTTP\Response;

class TypedResponse extends Response
     * @var array|object
    private $rawData;

    public function __construct()
        $config = config('App');


    public function setJSON($body, bool $unencoded = false)
        $this->rawData = $body;
        return parent::setJSON($body, $unencoded);

     * @return array|object
    public function getRawData()
        return $this->rawData;

Now, we can use it like before, but we also will have the original data passed into the response:


namespace App\Controllers\Api;

use App\Controllers\BaseController;
use App\ViewiBridge\TypedResponse;
use Components\Models\PostModel;

class Posts extends BaseController
    public function index($id): TypedResponse
        $postModel          = new PostModel();
        $postModel->Id      = (int) $id;
        $postModel->Name    = 'CodeIgniter4 ft. Viewi';
        $postModel->Version = 1;

        $response = (new TypedResponse())->setJSON($postModel);
        return $response;

This will pass this typed data as a response here:


namespace Components\Views\Posts;

use Components\Models\PostModel;
use Viewi\Components\BaseComponent;
use Viewi\Components\Http\HttpClient;

class PostsPage extends BaseComponent
    public string $title = 'Viewi - Reactive application for PHP';

    public ?PostModel $post = null;

    public function __construct(private HttpClient $http, private int $postId)

    public function init()
        $this->http->get("/api/posts/{$this->postId}")->then(function (PostModel $data) {
            $this->post = $data;
        }, function ($error) {
            echo $error;

Important note: model classes should be defined within your Viewi application. Using models outside of it will cause an error. If you are using a database model, you will need to convert it to the Viewi model type.

Viewi handler

Viewi handler is our 404 CodeIgniter route that will pass the execution to your Viewi application.


namespace App\ViewiBridge;

use App\Controllers\BaseController;
use Exception;
use Throwable;
use Viewi\App;
use Viewi\Components\Http\Message\Request;
use Viewi\Router\ComponentRoute;
use Viewi\Router\Router;

class ViewiHandler extends BaseController
    protected static App $viewiApp;
    protected static Router $viewiRouter;

    public function handle()
        $urlPath = str_replace('/index.php', '', $this->request->getUri()->getPath());
        $requestMethod = $this->request->getMethod();
        $match = self::$viewiRouter->resolve($urlPath, $requestMethod);
        if ($match === null) {
            throw new Exception('No route was matched!');
        /** @var RouteItem */
        $routeItem = $match['item'];
        $action = $routeItem->action;

        if ($action instanceof ComponentRoute) {
            $viewiRequest = new Request($urlPath, strtolower($requestMethod));
            $response = self::$viewiApp->engine()->render($action->component, $match['params'], $viewiRequest);

            foreach ($response->headers as $key => $value) {
                $this->response->setHeader($key, $value);
            $this->response->setStatusCode(isset($response->headers['Location']) ? 302 : $response->status);
        } else {
            throw new Exception('Unknown action type.');

    public static function setViewiApp(App $viewiApp)
        self::$viewiApp = $viewiApp;
        self::$viewiRouter = $viewiApp->router();

This will resolve Viewi route, call the render action for the assigned component, and convert it to the CodeIgniter4 response:

$match = self::$viewiRouter->resolve($urlPath, $requestMethod);
$response = self::$viewiApp->engine()->render($action->component, $match['params'], $viewiRequest);
foreach ($response->headers as $key => $value) {
    $this->response->setHeader($key, $value);
$this->response->setStatusCode(isset($response->headers['Location']) ? 302 : $response->status);

Viewi bridge

Viewi bridge is responsible for handling the server-side rendering (SSR) internal requests.

interface IViewiBridge
    // file_exists - Checks whether a file or directory exists
    function file_exists(string $filename): bool;

    // is_dir - Tells whether the filename is a directory
    function is_dir(string $filename): bool;

    // file_get_contents - Reads entire file into a string
    function file_get_contents(string $filename): string | false;

    // request - Server-side internal request handler. Request that comes from Viewi component.
    function request(Request $request): mixed;

In our case, it will look like this:


namespace App\ViewiBridge;

use CodeIgniter\Config\Services;
use CodeIgniter\HTTP\IncomingRequest;
use CodeIgniter\HTTP\URI;
use CodeIgniter\HTTP\UserAgent;
use Viewi\Bridge\DefaultBridge;
use Viewi\Components\Http\Message\Request;

class ViewiCodeIgniterBridge extends DefaultBridge
    public function __construct()

    public function request(Request $viewiRequest): mixed
        if ($viewiRequest->isExternal) {
            return parent::request($viewiRequest);

        // simulate a new internal request base on SSR Viewi request
        /** @var CodeIgniter $app */
        $app = Services::codeigniter(null, false);
        $context = is_cli() ? 'php-cli' : 'web';

        $uri       = new URI();
        $userAgent = new UserAgent();
        $request   = new IncomingRequest(
        // handle the request
        $response = $app->run(null, true);

        // extract typed data if possible
        if ($response instanceof TypedResponse) {
            return $response->getRawData();

        // by default we convert it from JSON
        return json_decode($response->getBody());

Setting up the 404 route

In you app\Config\Routes.php:

 * @var RouteCollection $routes

$routes->get('api/posts/(:num)', [Posts::class, 'index']);

 * Viewi set up
 * The idea is to let Viewi handle its own routes by registering a 404 action
 * @param RouteCollection $routes 
 * @return void 
function viewiSetUp(RouteCollection $routes)
    // initialize Viewi application
     * @var App
    $app = require __DIR__ . '/../ViewiApp/viewi.php';
    require __DIR__ . '/../ViewiApp/routes.php';
    // create Viewi bridge
    $bridge = new ViewiCodeIgniterBridge();
    // register a bridge in Viewi app
    $app->factory()->add(IViewiBridge::class, function () use ($bridge) {
        return $bridge;
    // pass Viewi app to our handler
    // set 404 route


Build Viewi application

Viewi application is not about PHP. It is also a fully capable JavaScript application.

To set it up you need to perform simple steps.

If you are using vendor/bin/viewi new that may not be necessary.

But if you are cloning this repository you will need to install NPM packages.

Assuming that you have installed composer packages:

cd app\ViewiApp\js

npm install

Wait for the installation.

Watching mode

Watching mode will monitor your Viewi application for changes and will trigger a build process automatically.

Go to your Viewi application js folder

cd app\ViewiApp\js

Run NPM watch command

npm run watch

You will need to keep two terminals open in order to run this and ReactPHP server for development.

Watch mode is optional, please follow watch-mode for more.

Open the second terminal and run:

php spark serve

Navigate to http://localhost:8080/.

Thanks and feel free to review, ask questions, contribute in any way.