@orieljs/framework 0.1.0-alpha.6 → 0.1.0-alpha.8

package/docs/inertia.md

@@ -0,0 +1,485 @@
+# Inertia
+
+Inertia lets you write your pages as React, Vue, Svelte, Solid or Angular components, while your routes and controllers
+stay on the server, with no API to build in between.
+
+## Introduction
+
+An Inertia page is a component in `resources/js/pages`. Your controller returns the page's name and its props; Inertia
+renders the component with them, in the browser on later visits and, with server-side rendering, on the server for the
+first one. Links and forms make requests as a single-page app does, and the server answers with the next page's props as
+JSON.
+
+Oriel follows `inertia-laravel` on the server and speaks the protocol of the official Inertia clients. Its adapters,
+one per framework, add typed pages and Oriel's `route()`:
+
+| Framework | Package | Starter kit |
+| --- | --- | --- |
+| React | `@orieljs/inertia-react` | `--inertia=react` |
+| Vue | `@orieljs/inertia-vue` | `--inertia=vue` |
+| Svelte | `@orieljs/inertia-svelte` | `--inertia=svelte` |
+| Solid | `@orieljs/inertia-solid` | `--inertia=solid` |
+| Angular | `@orieljs/inertia-angular` | `--inertia=angular` |
+
+The React, Vue and Svelte adapters are the official Inertia adapters, re-exported with Oriel's additions. The Solid
+and Angular adapters are Oriel's own, with the same API in each framework's idiom. A new app from an Inertia
+[starter kit](starter-kits.md) has everything below set up.
+
+## Server-side setup
+
+### Creating responses
+
+An action returns a page with `inertia()`, its component's name and its props:
+
+```ts title="app/Http/Controllers/PostController.ts"
+import { inertia } from '@orieljs/framework'
+import { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class PostController extends Controller {
+  /** Show the blog's posts. */
+  async index() {
+    return inertia('Posts/Index', {
+      posts: await Post.latest().get(),
+    })
+  }
+}
+```
+
+The component's name is its path under `resources/js/pages`, without the extension: `Posts/Index` is
+`resources/js/pages/Posts/Index.tsx` (or `.vue`, `.svelte`, `.component.ts`). Models in the props reach the page as
+their JSON, so their `hidden` attributes stay on the server.
+
+A page with no data of its own needs no controller: `Route.inertia()` routes a URI to it.
+
+```ts title="routes/web.ts"
+import { Route } from '@orieljs/framework'
+
+Route.inertia('/about', 'About').name('about')
+```
+
+### The root view
+
+The first visit loads the root view, `resources/views/app.tsx`, which writes the HTML document around the page. It
+places the page's data with `inertiaBody(page)`, the server-rendered head with `inertiaHead(page)`, and your scripts and
+styles with [`vite()`](vite.md). A React app adds `viteReactRefresh()` before `vite()`:
+
+```tsx title="resources/views/app.tsx"
+import { inertiaBody, inertiaHead, vite, viteReactRefresh } from '@orieljs/framework'
+import type { InertiaPage } from '@orieljs/framework/contracts'
+
+export default function App({ page }: { page: InertiaPage }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        {inertiaHead(page)}
+        {viteReactRefresh()}
+        {vite(['resources/css/app.css', 'resources/js/app.tsx'])}
+      </head>
+      <body>{inertiaBody(page)}</body>
+    </html>
+  )
+}
+```
+
+### The middleware
+
+`HandleInertiaRequests`, in `app/Http/Middleware`, extends `InertiaMiddleware`, and `bootstrap/app.ts` appends it to the
+`web` group. It answers in the Inertia protocol: a JSON page on Inertia requests, a 409 when your assets changed since
+the page was loaded, and a 303 after a `PUT`, `PATCH` or `DELETE` that redirects. `node oriel inertia:middleware` writes
+one for an app that hasn't.
+
+Its `share()` gives every page some props, merged with the validation errors it shares itself:
+
+```ts title="app/Http/Middleware/HandleInertiaRequests.ts"
+import { Auth, config, InertiaMiddleware } from '@orieljs/framework'
+import type { HttpRequest } from '@orieljs/framework/contracts'
+import type { User } from '../../Models/User'
+
+export class HandleInertiaRequests extends InertiaMiddleware {
+  /** The root view loaded on the first page visit: resources/views/app.tsx. */
+  protected override rootViewName = 'app'
+
+  /** Props shared with every page. */
+  override async share(request: HttpRequest) {
+    const user = await Auth.user<User>()
+
+    return {
+      ...(await super.share(request)),
+      name: String(config('app.name')),
+      auth: { user: user === undefined ? null : { id: user.id, name: user.name, email: user.email } },
+    }
+  }
+}
+```
+
+`version()` returns your assets' version: a hash of `app.asset_url` when you set one, else of
+`public/build/manifest.json`. A page loaded with an older version is reloaded in full on its next visit.
+
+### Shared data
+
+Besides the middleware's `share()`, `Inertia.share()` shares props from anywhere in a request, such as a controller:
+
+```ts
+Inertia.share('appName', 'Blog')
+```
+
+`Inertia.flash()` stores data for the next page only, which reads it as `page.flash`, as session flash data works.
+
+### Redirects
+
+Redirect as anywhere else in your app: `redirect().route('posts.index')`, or `back()`. Inertia follows the redirect
+and shows the next page. To leave the app, to an external site or a page that isn't Inertia's, `Inertia.location()`
+makes the browser load the URL in full:
+
+```ts
+Route.get('/billing', () => Inertia.location('https://example.com/billing'))
+```
+
+### Props: deferred, optional and merged
+
+A prop can be a function, which runs only when the prop is sent. These helpers choose when that is:
+
+| Helper | The prop is sent |
+| --- | --- |
+| `Inertia.defer(fn, group?)` | In a request the page makes right after it renders, so the page shows sooner; props of one group come together |
+| `Inertia.optional(fn)` | Only in a partial reload that asks for it |
+| `Inertia.always(value)` | In every response, even a partial reload that didn't ask for it |
+| `Inertia.merge(value)`, `Inertia.deepMerge(value)` | And merged into the page's current value on a reload, such as the next page of a list |
+| `Inertia.once(fn)` | Once: the client keeps it for the next pages |
+| `Inertia.scroll(paginator)` | As a page of an infinite scroll, with its page numbers |
+
+```ts title="app/Http/Controllers/DashboardController.ts"
+import { Inertia, inertia } from '@orieljs/framework'
+import { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class DashboardController extends Controller {
+  async index() {
+    return inertia('Dashboard', {
+      latest: await Post.latest().limit(5).get(),
+      drafts: Inertia.defer(() => Post.whereNull('published_at').get()),
+      stats: Inertia.optional(() => Post.count()),
+    })
+  }
+}
+```
+
+A partial reload asks the server for some props only, such as `router.reload({ only: ['stats'] })` in the page.
+
+## Client-side setup
+
+The browser entry, `resources/js/app.tsx` (`app.ts` in the Vue, Svelte and Angular kits), starts Inertia with your
+pages' folder:
+
+```tsx title="resources/js/app.tsx"
+import { createInertiaApp } from '@orieljs/inertia-react'
+
+const appName = import.meta.env.VITE_APP_NAME || 'Oriel'
+
+createInertiaApp({
+  pages: './pages',
+  title: (title) => (title ? `${title} – ${appName}` : appName),
+})
+```
+
+`title` formats every page's title. The `oriel()` [Vite](vite.md) plugin sets up each framework's own Vite plugin.
+
+## Pages
+
+A page component receives its props. They are typed: `node oriel inertia:types` reads the `inertia()` calls of your
+controllers and routes and writes `resources/js/oriel/pages.d.ts`, so each page knows its props, and the props your
+middleware shares. The kits' Vite plugin runs it when Vite starts, and again when your server code changes.
+
+```tsx tab="React" title="resources/js/pages/Posts/Index.tsx"
+import { Head, Link, route, type PageProps } from '@orieljs/inertia-react'
+
+export default function Index({ posts }: PageProps<'Posts/Index'>) {
+  return (
+    <>
+      <Head title="Posts" />
+      <ul>
+        {posts.map((post) => (
+          <li key={post.id}>
+            <Link href={route('posts.show', post.slug)}>{post.title}</Link>
+          </li>
+        ))}
+      </ul>
+    </>
+  )
+}
+```
+```vue tab="Vue" title="resources/js/pages/Posts/Index.vue"
+<script setup lang="ts">
+import { Head, Link, route, usePage } from '@orieljs/inertia-vue'
+
+const page = usePage<'Posts/Index'>()
+</script>
+
+<template>
+  <Head title="Posts" />
+  <ul>
+    <li v-for="post in page.props.posts" :key="post.id">
+      <Link :href="route('posts.show', post.slug)">{{ post.title }}</Link>
+    </li>
+  </ul>
+</template>
+```
+```svelte tab="Svelte" title="resources/js/pages/Posts/Index.svelte"
+<script lang="ts">
+  import { Link, route, type PageProps } from '@orieljs/inertia-svelte'
+
+  let { posts }: PageProps<'Posts/Index'> = $props()
+</script>
+
+<svelte:head>
+  <title>Posts</title>
+</svelte:head>
+
+<ul>
+  {#each posts as post (post.id)}
+    <li><Link href={route('posts.show', post.slug)}>{post.title}</Link></li>
+  {/each}
+</ul>
+```
+```tsx tab="Solid" title="resources/js/pages/Posts/Index.tsx"
+import { Head, Link, route, type PageProps } from '@orieljs/inertia-solid'
+import { For } from 'solid-js'
+
+export default function Index(props: PageProps<'Posts/Index'>) {
+  return (
+    <>
+      <Head title="Posts" />
+      <ul>
+        <For each={props.posts}>
+          {(post) => (
+            <li>
+              <Link href={route('posts.show', post.slug)}>{post.title}</Link>
+            </li>
+          )}
+        </For>
+      </ul>
+    </>
+  )
+}
+```
+```ts tab="Angular" title="resources/js/pages/Posts/Index.component.ts"
+import { Component, input } from '@angular/core'
+import { Head, Link, route } from '@orieljs/inertia-angular'
+
+@Component({
+  selector: 'posts-index',
+  imports: [Head, Link],
+  template: `
+    <o-head title="Posts" />
+    <ul>
+      @for (post of posts(); track post.id) {
+        <li><a oLink [href]="route('posts.show', post.slug)">{{ post.title }}</a></li>
+      }
+    </ul>
+  `,
+})
+export default class Index {
+  readonly posts = input.required<{ id: number; title: string; slug: string }[]>()
+
+  protected readonly route = route
+}
+```
+
+> [!NOTE]
+> A Vue page reads its props with `usePage<'Posts/Index'>()`, typed by the page's name, where Inertia's own Vue docs
+> declare them with `defineProps`: Vue's compiler can't resolve the generated page types in
+> `defineProps<PageProps<'Posts/Index'>>()`. An Angular page receives each prop as a signal input. Svelte has no
+> Inertia `Head` component: the kits use `<svelte:head>`.
+
+### Links and the route helper
+
+`Link` (in Angular, the `oLink` directive on an `<a>`) visits a page without reloading the document. `route()` gives a
+named route's URL, typed: once `node oriel route:types` has run, a wrong name or a missing parameter is a type error.
+`isCurrentRoute('posts.*')` tells you whether the current page's route matches, for an active link. Both work during
+server-side rendering, from the URL being rendered.
+
+`router` makes visits from code: `router.visit(url)`, `router.post(url, data)`, `router.reload({ only: ['stats'] })`.
+
+## Forms
+
+`useForm()` holds a form's data, sends it, and gives back the validation errors, one per field, and whether the
+request is in flight:
+
+```tsx tab="React" title="resources/js/pages/Posts/Create.tsx"
+import { route, useForm } from '@orieljs/inertia-react'
+import type { FormEvent } from 'react'
+
+export default function Create() {
+  const { data, setData, post, processing, errors } = useForm<{ title: string }>({ title: '' })
+
+  const submit = (event: FormEvent) => {
+    event.preventDefault()
+    post(route('posts.store'))
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <input value={data.title} onChange={(event) => setData('title', event.target.value)} />
+      {errors.title && <p className="error">{errors.title}</p>}
+
+      <button type="submit" disabled={processing}>
+        Publish
+      </button>
+    </form>
+  )
+}
+```
+```vue tab="Vue" title="resources/js/pages/Posts/Create.vue"
+<script setup lang="ts">
+import { route, useForm } from '@orieljs/inertia-vue'
+
+const form = useForm({
+  title: '',
+})
+
+const submit = () => {
+  form.post(route('posts.store'))
+}
+</script>
+
+<template>
+  <form @submit.prevent="submit">
+    <input v-model="form.title" />
+    <p v-if="form.errors.title" class="error">{{ form.errors.title }}</p>
+
+    <button type="submit" :disabled="form.processing">Publish</button>
+  </form>
+</template>
+```
+```svelte tab="Svelte" title="resources/js/pages/Posts/Create.svelte"
+<script lang="ts">
+  import { route, useForm } from '@orieljs/inertia-svelte'
+
+  const form = useForm({
+    title: '',
+  })
+
+  function submit(event: SubmitEvent) {
+    event.preventDefault()
+    form.post(route('posts.store'))
+  }
+</script>
+
+<form onsubmit={submit}>
+  <input bind:value={form.title} />
+  {#if form.errors.title}
+    <p class="error">{form.errors.title}</p>
+  {/if}
+
+  <button type="submit" disabled={form.processing}>Publish</button>
+</form>
+```
+```tsx tab="Solid" title="resources/js/pages/Posts/Create.tsx"
+import { route, useForm } from '@orieljs/inertia-solid'
+import { Show } from 'solid-js'
+
+export default function Create() {
+  const form = useForm<{ title: string }>({ title: '' })
+
+  const submit = (event: SubmitEvent) => {
+    event.preventDefault()
+    form.post(route('posts.store'))
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <input value={form.data.title} onInput={(event) => form.setData('title', event.currentTarget.value)} />
+      <Show when={form.errors.title}>
+        <p class="error">{form.errors.title}</p>
+      </Show>
+
+      <button type="submit" disabled={form.processing}>
+        Publish
+      </button>
+    </form>
+  )
+}
+```
+```ts tab="Angular" title="resources/js/pages/Posts/Create.component.ts"
+import { Component } from '@angular/core'
+import { route, useForm } from '@orieljs/inertia-angular'
+
+@Component({
+  selector: 'posts-create',
+  template: `
+    <form (submit)="submit($event)">
+      <input #title [value]="form.data.title" (input)="form.setData('title', title.value)" />
+      @if (form.errors.title) {
+        <p class="error">{{ form.errors.title }}</p>
+      }
+
+      <button type="submit" [disabled]="form.processing">Publish</button>
+    </form>
+  `,
+})
+export default class Create {
+  protected readonly form = useForm<{ title: string }>({ title: '' })
+
+  protected submit(event: SubmitEvent): void {
+    event.preventDefault()
+    this.form.post(route('posts.store'))
+  }
+}
+```
+
+A failed validation sends the user back to the page, with the errors (see
+[Displaying errors in Inertia pages](validation.md#displaying-errors-in-inertia-pages)). Each adapter also has a `Form`
+component (Angular's `form[oForm]`), which sends a plain HTML form's fields without `useForm()`.
+
+### Precognition
+
+On a route with the `precognitive` middleware, the React, Vue and Svelte forms can validate a field while the user fills
+it in: give `useForm()` the method and the URL first, `useForm('post', route('posts.store'), { title: '' })`, then call
+`form.validate('title')`; `Form` has a `validate()` too. The Solid and Angular forms don't offer Precognition yet.
+[Precognition](validation.md#precognition) describes the server side, and why the action validates first.
+
+## More Inertia features
+
+Each adapter has Inertia's components and hooks for the props above, under Inertia's names (Angular's are directives):
+
+| Feature | React, Vue, Svelte, Solid | Angular |
+| --- | --- | --- |
+| Deferred props, with a fallback while they load | `Deferred` | `oDeferred` directive |
+| Loading props when an element scrolls into view | `WhenVisible` | `oWhenVisible` directive |
+| Infinite scrolling of an `Inertia.scroll()` prop | `InfiniteScroll` | `<o-infinite-scroll>` |
+| Reloading props on an interval | `usePoll()` | `usePoll()` |
+| Prefetching pages before a click | `usePrefetch()`, `prefetch` on `Link` | `usePrefetch()`, `prefetch` on `oLink` |
+| Keeping local state in the browser's history | `useRemember()` | `useRemember()` |
+| The page's title and meta tags | `Head` (Svelte: `<svelte:head>`) | `<o-head>` |
+
+They work as Inertia's documentation describes, at [inertiajs.com](https://inertiajs.com).
+
+## Server-side rendering
+
+The React, Vue, Svelte and Solid kits render the first visit on the server, so it arrives as HTML. `npm run build`
+builds the server bundle from `resources/js/ssr.*` into `bootstrap/ssr`, and `node oriel inertia:start-ssr` runs it;
+when no SSR server answers, the pages are rendered in the browser. [Inertia SSR](starter-kits.md#inertia-ssr) and
+[The SSR server](deployment.md#the-ssr-server) cover running it. `inertia.ssr.enabled`, from `INERTIA_SSR_ENABLED`,
+turns it off.
+
+## History encryption
+
+Inertia keeps each page's props in the browser's history, so the back button can show them again. To keep a signed-in
+user's data out of it after they sign out, encrypt it: `INERTIA_ENCRYPT_HISTORY=true` encrypts every page's state, and
+the `inertia.encrypt` middleware does it for some routes. `Inertia.clearHistory()` clears the encrypted history, such
+as when a user signs out.
+
+## Adapter differences
+
+| | React, Vue, Svelte | Solid | Angular |
+| --- | --- | --- | --- |
+| Server-side rendering | Yes | Yes | No |
+| Precognition | Yes | No | No |
+| `useHttp()` | Yes | No | No |
+
+The Angular adapter's other limits are in its package's README: track a form's array rows by `$index` or a stable id,
+not by the item, since `useForm` copies the objects along a dotted path on each write; and once a page uses `<o-head>`,
+a later `Title.setTitle()` is overwritten.

package/docs/installation.md

@@ -0,0 +1,209 @@
+# 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:
+
+```sh
+npm create @orieljs@latest blog
+```
+
+The same installer runs with pnpm, Bun and Yarn:
+
+```sh
+pnpm create @orieljs blog
+bun create @orieljs blog
+yarn 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:
+
+| Option | The kit |
+| --- | --- |
+| `--inertia=react` | Inertia pages in React (a bare `--inertia` means React) |
+| `--inertia=vue`, `--inertia=svelte`, `--inertia=solid`, `--inertia=angular` | Inertia pages in Vue, Svelte, Solid or Angular |
+| `--live` | Live: server-driven components written in TSX |
+| `--api` | A JSON API with personal access tokens, and no pages |
+
+[Starter kits](starter-kits.md) describes what each kit contains.
+
+> [!NOTE]
+> With npm, the options go after `--`, so npm passes them on to the installer:
+> `npm create @orieljs@latest blog -- --inertia=vue`. pnpm, Bun and Yarn take them directly.
+
+### Installer options
+
+| Option | What it does |
+| --- | --- |
+| `--pm <npm\|pnpm\|yarn\|bun>` | The package manager to use (by default, the one running the installer) |
+| `--install`, `--no-install` | Install the dependencies, set the app key, create the database and build the assets (default: yes) |
+| `--git`, `--no-git` | Start a git repository with a first commit (default: yes) |
+| `-f`, `--force` | Empty a folder that isn't empty, without asking (a `.git` folder stays) |
+| `-y`, `--yes` | Ask nothing, and take the defaults for everything not given: `oriel-app`, React, install, git |
+| `-h`, `--help` | List the options |
+| `-v`, `--version` | Print the installer's version |
+
+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:
+
+```sh
+npm install
+node oriel key:generate
+node oriel migrate --force
+npm 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:
+
+```sh
+cd blog
+npm run dev
+node 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](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.
+
+> [!NOTE]
+> Vite reloads the page when a view, a route file or a Live component changes, often before the server has
+> restarted, and it doesn't reload the page again once the new server is up. After `serve --watch` prints
+> "Restarting server...", reload the page once more to see your change.
+
+`oriel serve` listens on `127.0.0.1`, on port 8000 or the one the `PORT` variable names. `--host` and `--port` choose
+others:
+
+```sh
+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`.
+
+> [!TIP]
+> Every command the framework knows is listed by `node oriel list`, and `node oriel help <command>` explains one.
+
+## 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](configuration.md) 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`:
+
+```sh
+npm install pg
+```
+
+then set the `DB_*` variables in `.env`:
+
+```dotenv
+DB_CONNECTION=pgsql
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_DATABASE=blog
+DB_USERNAME=root
+DB_PASSWORD=
+```
+
+Create the database on your server, then run your migrations:
+
+```sh
+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](structure.md), and how it reads its settings in
+[Configuration](configuration.md). Your app's routes live in `routes/web.ts`: [Routing](routing.md) 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](queues.md). When your app is ready to go live, [Deployment](deployment.md) covers building and
+running it on a server.
+
+To learn how an app runs, read [Request lifecycle](lifecycle.md), [Service container](container.md) and
+[Facades](facades.md).