Getting started

Directory structure

A new Oriel app has Laravel's layout: your code in app, your settings in config, your routes in routes, and a few folders that Oriel reads by itself.

Introduction#

The layout is a starting point, not a rule: your files import each other by relative path, so a class can live wherever suits your app. A few folders are the exception. Oriel looks in them by name to find your models, your commands, your listeners and your policies, as Folders Oriel discovers lists.

Every starter kit is built from layers: base, which every app has, then the layers of its kit. The starter kits' layers section says which folders each layer adds.

The root directory#

The app directory#

app holds the core code of your app: its controllers, models, providers and most of its other classes. The app directory section looks inside it.

The bootstrap directory#

bootstrap/app.ts creates your app: it names your route files, configures middleware and error handling, and lists your service providers through bootstrap/providers.ts. Your server, your oriel command and your tests all start from it.

The Inertia kits with server-side rendering build their SSR bundle into bootstrap/ssr, which git ignores. There is no bootstrap/cache: Oriel has no route or config cache to store.

The config directory#

config holds your app's configuration files, one TypeScript module per part of the framework.

The database directory#

database holds your migrations (database/migrations), your model factories (database/factories) and your seeders (database/seeders). A new app keeps its SQLite database here too, in database/database.sqlite, which git ignores.

The public directory#

public holds the files the server sends as they are, such as favicon.svg, and public/index.ts, the entry point that runs your app in production (see Deployment). A request for a file that exists in public gets the file before your routes run. TypeScript files and dotfiles there are never sent.

Vite builds your scripts and styles into public/build, and while npm run dev runs it writes public/hot, which tells your pages to load their assets from Vite. node oriel storage:link adds public/storage, a link to storage/app/public. Git ignores all three.

The resources directory#

resources holds your views and the uncompiled sources of your pages:

• resources/views: your views, written in TSX, such as welcome.tsx. In the Inertia kits, app.tsx there is the root view every page is rendered into.
• resources/css/app.css: the kits' stylesheet, with Tailwind and the Oriel theme.
• resources/js: your pages' scripts. In the Inertia kits, the pages are in resources/js/pages, with their components and layouts beside them.
• resources/js/oriel: the route and page types that route:types and inertia:types write, which git ignores.

The API kit has no resources folder until npm run typecheck writes resources/js/oriel/routes.ts.

The routes directory#

routes holds your route files. A new app has two:

• routes/web.ts: the routes of your pages, in the web middleware group, which gives them the session, cookie encryption and CSRF protection.
• routes/console.ts: your closure commands, such as the inspire command a new app comes with, and your scheduled tasks.

The kits with pages add routes/auth.ts, for registration, signing in and out, password resets and email verification, and routes/settings.ts, for the settings pages. The API kit has routes/api.ts in place of routes/web.ts: its routes are stateless, their URIs start with /api, and their users sign in with tokens. node oriel install:api adds a routes/api.ts to another app. bootstrap/app.ts lists the files to load (see Routing).

The storage directory#

storage holds the files your app and the framework write:

• storage/app/private: the local disk, for files your app keeps to itself.
• storage/app/public: the public disk, for files anyone may download, such as avatars. node oriel storage:link links public/storage to it.
• storage/framework/cache/data: the file cache store.
• storage/framework/sessions: the file session driver's sessions.
• storage/framework/views: kept from Laravel's layout. Oriel's views are TSX modules, so nothing compiles into it.
• storage/logs: your logs, oriel.log, and mail.log when mail is logged to its own channel.

Git keeps the folders and ignores what is written into them.

The tests directory#

tests holds your tests: tests/Feature for tests that send requests to your app or run its commands, and tests/Unit for the rest, with tests/TestCase.ts, the class they boot the app with. A test file's name ends in .test.ts, or .test.tsx. Run them with node oriel test, or with npm test, and on Bun with npm run test:bun.

The types directory#

types holds the type declarations Oriel writes for your app:

• types/models.d.ts: your models' columns, written by node oriel model:types from your database. migrate, migrate:fresh and migrate:refresh write it again when they finish, outside production. It is in git, so your app type-checks on a fresh clone.
• types/routes.d.ts: your route names and parameters, written by node oriel route:types. Git ignores it.

The node_modules directory#

node_modules holds your dependencies, as vendor does in a Laravel app. Your package manager writes it, and git ignores it.

The files at the root#

The app directory#

Most of your app lives in app. A new app has app/Http, with its base Controller, app/Models, with the User model, and app/Providers, with the AppServiceProvider. The other folders appear when a make: command writes a class into them: app/Console doesn't exist until you run make:command. node oriel list shows every make: command.

The Console directory#

app/Console/Commands holds your console commands, written by make:command. Oriel finds them by itself.

The Events directory#

app/Events holds your event classes, written by make:event.

The Http directory#

app/Http holds what handles a request: Controllers (make:controller), Middleware (make:middleware), form Requests (make:request) and API Resources (make:resource).

The Jobs directory#

app/Jobs holds your queued jobs, written by make:job.

The Listeners directory#

app/Listeners holds the classes that handle your events, written by make:listener. Oriel finds each one by itself, and registers it for the events its static listensTo names.

The Live directory#

app/Live holds the Live kit's components, and the ones make:live writes. Each component's name comes from its path: app/Live/Auth/Login.tsx is auth.login.

The Mail directory#

app/Mail holds your mail classes, written by make:mail, which also writes the mail's view in resources/views/mail.

The Models directory#

app/Models holds your models, written by make:model. Oriel finds them by itself: a route parameter named after a model receives it, and model:types writes their columns.

The Notifications directory#

app/Notifications holds your notifications, written by make:notification.

The Policies directory#

app/Policies holds your authorization policies, written by make:policy. A policy named after a model, as PostPolicy for Post, applies to that model without being registered.

The Providers directory#

app/Providers holds your service providers. A new app has AppServiceProvider. make:provider writes a new one there, which you then add to the list in bootstrap/providers.ts.

The Rules directory#

app/Rules holds your validation rule objects, written by make:rule.

The other directories#

make:cast writes into app/Casts and make:observer into app/Observers. The kits with pages also have app/Support/GettingStarted.ts, which builds the dashboard's checklist.

Folders Oriel discovers#

A TypeScript module runs only when something imports it, so Oriel imports these folders itself, and registers what it finds there:

Each folder is read with the folders inside it, except app/Policies and database/factories. A class in another folder works, but isn't discovered: register it yourself, as Event.listen() does for a listener or Gate.policy() for a policy.

Other folders are read when they are needed: config when the app is created, resources/views for each view, database/migrations by migrate, and database/seeders by db:seed.

The starter kits' layers#

Each kit is the base layer and its own layers, applied in order, a later layer's file replacing an earlier one's:

What each layer adds:

Each layer but inertia also adds to package.json (web its dev dependencies only), and all but the five framework layers add their tests.

Starter kits describes what the kits do with them.

Generated and ignored files#

Some files are written by a command rather than by you. Don't edit them: run the command again.

Git also ignores node_modules, the files under storage, .env.backup, .DS_Store and Yarn's .yarn/install-state.gz.