Getting started

Installation

Oriel is a full-stack TypeScript framework for Node and Bun, in the spirit of Laravel. Create an app with your package manager and one of seven starter kits.

Meet Oriel#

Oriel gives a TypeScript app what Laravel gives a PHP one: routing, controllers and middleware, models and migrations, validation, authentication, queues, mail and the scheduler, under Laravel's names. Your pages are Inertia pages in React, Vue, Svelte, Solid or Angular, or Live components rendered on the server, and the same app can serve a JSON API.

Creating an Oriel application#

Requirements#

You need Node 22 or later, or Bun 1.2 or later. Nothing is installed globally: the installer runs through your package manager, and each app has its own oriel command. A new app keeps its data in SQLite, so you don't need a database server to start.

Creating an application#

Create an app with your package manager's create command:

npm create @orieljs@latest blog

The same installer runs with pnpm, Bun and Yarn:

pnpm create @orieljs blogbun create @orieljs blogyarn create @orieljs blog

npm create oriel-app is the same installer under another name: both run create-oriel-app at the same version.

The installer asks for the app's name, unless you gave one, then for a stack (Inertia, Live or an API) and, for Inertia, its framework, and last whether to install the dependencies and start a git repository. The name is the last part of the folder you create the app in, and it must be a valid npm package name: lower case, with no spaces. When the folder isn't empty, the installer asks before it removes the files in it.

Choosing a starter kit#

The kits with pages come with registration, login, email verification, password reset, a dashboard, and profile, password and appearance settings. The API kit has registration, login, logout and password reset as JSON endpoints, with personal access tokens and no pages. Pick one in the prompt, or name it with an option:

Starter kits describes what each kit contains.

Installer options#

The installer asks its questions only in a terminal: when its input and output are a terminal, the CI variable isn't set and you didn't pass --yes. In a script or on CI, pass the kit as an option or --yes; without either, the installer stops with "No stack chosen: pass --inertia[=<framework>], --live or --api (or --yes for React).". A folder that isn't empty needs --force there.

What the installer does#

It copies the kit into the new folder and writes the app's package.json for your package manager. It writes .env from .env.example, with APP_NAME set to the app's name, and a CI workflow, .github/workflows/ci.yml, that installs the app, migrates a fresh database, type-checks and tests the app, builds its assets, and checks that it serves. The workflow runs on Node 22, Node 24 and Bun, or on Bun alone for an app made with Bun.

Unless you pass --no-install, it then runs the first commands for you:

npm installnode oriel key:generatenode oriel migrate --forcenpm run build

key:generate writes your app's secret key, APP_KEY, into .env, and migrate creates the SQLite database, database/database.sqlite, with the tables a new app needs: users, password reset tokens, sessions, cache, cache locks, jobs, job batches, failed jobs, personal access tokens and notifications. The API kit has no assets, so it has no build step.

Last, unless you pass --no-git, it runs git init and makes a first commit, "Initial commit". It skips this when git isn't installed or the folder is inside a git repository already. When the commit fails, for example because git has no user.name and user.email yet, the repository stays, with your files added but not committed.

Package managers#

The installer works with npm, pnpm, Yarn (Yarn 1, and Yarn 2 or later such as Yarn 4) and Bun. The app it writes follows the one you chose:

• pnpm: package.json names pnpm and its version in packageManager, and pnpm-workspace.yaml lists the dependencies allowed to run install scripts (before pnpm 10.26, a pnpm field in package.json does).
• Yarn 2 or later: package.json names Yarn and its version in packageManager, and .yarnrc.yml sets nodeLinker: node-modules, since the app's tools don't run under Plug'n'Play. Yarn 1 needs neither.
• Bun: the app runs bun oriel wherever another app runs node oriel: in its scripts, in the commands the installer runs and prints, and in its CI workflow, which runs on Bun only.

The commands in the kit's README.md are rewritten for your package manager too.

Running your application#

When the installer is done, it prints the commands to run while you work:

cd blognpm run devnode oriel serve --watch

Run the last two in two terminals. In one, npm run dev starts Vite, which serves your pages' scripts and styles and updates them in the browser as you edit them. In the other, node oriel serve --watch starts your app's server.

Your app is at http://localhost:8000. --watch restarts the server when a file it runs changes: a TypeScript, JavaScript or JSON file in app, bootstrap, config, lang, resources/lang, resources/views or routes, .env or another .env.* file (not .env.example), package.json or tsconfig.json. Your pages' own scripts and styles, in resources/js and resources/css, are Vite's, and don't restart it.

oriel serve listens on 127.0.0.1, on port 8000 or the one the PORT variable names. --host and --port choose others:

node oriel serve --watch --host=0.0.0.0 --port=3000

The API kit has no Vite config and no dev script: node oriel serve --watch is all it needs. An app made with Bun runs bun run dev and bun oriel serve --watch.

If you passed --no-install, the printed commands start with the steps the installer skipped: npm install, node oriel key:generate, node oriel migrate and npm run build.

Initial configuration#

Your app's settings are in the config folder, one file per part of the framework: config/app.ts, config/database.ts, config/session.ts and so on. A new app runs as it is, but you may want to look at config/app.ts, which holds the app's name, URL and locale.

Environment based configuration#

The values that differ between your machine and your servers, such as the database's password or the mail server, come from the .env file at the root of your app, which the config files read with env(). The installer writes .env for you, and git ignores it: each machine has its own, and its secrets stay out of your repository. Configuration explains the file and env().

Databases and migrations#

A new app uses SQLite, in database/database.sqlite, which the installer created and migrated. To use PostgreSQL or MySQL instead, install its driver, pg or mysql2:

npm install pg

then set the DB_* variables in .env:

DB_CONNECTION=pgsqlDB_HOST=127.0.0.1DB_PORT=5432DB_DATABASE=blogDB_USERNAME=rootDB_PASSWORD=

Create the database on your server, then run your migrations:

node oriel migrate

For MySQL, DB_CONNECTION is mysql and the port is usually 3306.

Next steps#

Read how an app is laid out in Directory structure, and how it reads its settings in Configuration. Your app's routes live in routes/web.ts: Routing is the place to start writing your own code. When a request has slow work to do, such as sending mail or resizing images, hand it to a worker with Queues. When your app is ready to go live, Deployment covers building and running it on a server.

To learn how an app runs, read Request lifecycle, Service container and Facades.