The web app
apps/web is the dashboard. It is Flare’s Next.js app with its database and sign-in code replaced by calls to Laravel. It has no database of its own.
How a request flows
Section titled “How a request flows”- The browser asks the Next.js server for a page or submits a form.
- The Next.js server reads the visitor’s token from an httpOnly cookie.
- It calls Laravel with that token as a Bearer header.
- Laravel validates, checks its policy, reads or writes, and answers.
- The Next.js server renders the result.
The browser never calls Laravel and never sees the token. That is why Laravel needs no CORS setup for the dashboard.
The files that talk to Laravel
Section titled “The files that talk to Laravel”| File | What it does |
|---|---|
lib/laravel.ts |
The only fetch to Laravel. Adds the token. Every other file goes through it. |
app/auth-actions.ts |
Sign in and sign out. Sets and clears the token cookie. |
lib/session.ts |
Who is signed in, from GET /auth/me. |
lib/resource/store.ts |
List, read, create, update and delete for one resource. |
lib/dashboard.ts |
What the dashboard components import: the store per resource, stats and permissions. |
proxy.ts |
Sends visitors with no token cookie to /sign-in before a page renders. |
Everything else (tables, forms, fields, themes) is Flare’s and reads only the resource descriptors.
Files Laravel generates here
Section titled “Files Laravel generates here”Running nevela:resource or nevela:generate in apps/api writes into this app:
| File | Notes |
|---|---|
resources/<name>.resource.ts |
The dashboard’s description of the resource. Regenerated between the markers. |
resources/index.ts |
The list of all resources. The sidebar and dashboard home are built from it. |
app/dashboard/<slug>/page.tsx and the new, [id] and [id]/edit pages |
Written once. Change them freely. |
Do not edit fields in the .resource.ts file. Change the JSON descriptor in the Laravel app and regenerate, so both sides stay the same.
Three ways to add records
Section titled “Three ways to add records”Every resource’s list has them side by side, for anyone allowed to create:
| For | |
|---|---|
| New | One record, in the form. |
| Add several | The dozen you have in your head or on a piece of paper. A grid that opens with five blank rows; add more as you go. |
| Import CSV | A file somebody already has. |
In the grid, rows you leave empty are ignored, and the button says how many will be created (“Create 3 products”). The rows are saved together or not at all: if one is wrong, nothing is created and the mistake is shown on its row.
A field that doesn’t fit in a cell, an image or a file, has no column. If one of those is required the grid says so, and those records are for the form.
Insights
Section titled “Insights”Above every resource’s table there is an Insights panel, closed until you open it:
- Created per day, week or month, as a bar chart: the last 30 days, 26 weeks or 12 months.
- How the records split across each field that is a choice, an enum or a yes/no: a bar for every choice, with its count and its share.
The charts are of the rows the table is showing. Search, or filter the list to one category, and they redraw for that.
Nothing is counted until the panel is opened, so a list costs what it did before. Whether you left it open is remembered, for each resource, in your browser.
A resource gets this without being asked: the choices come from its descriptor. There is nothing to configure.
The trash
Section titled “The trash”Delete is not final. A deleted record goes to the Trash page, under Manage, where it can be restored for 30 days; the message that confirms a delete has an Undo on it. See The trash.
Two people editing the same record
Section titled “Two people editing the same record”When someone saves a record you have open in the edit form, your save doesn’t put back what they changed. The form sends the record’s updatedAt with your changes, and Laravel refuses them if anyone has saved since. The form then fits your changes and theirs together, field by field:
- A field only they changed takes their value.
- A field only you changed keeps yours.
- If none of your fields clash with theirs, the form saves again by itself. The message that says it saved names their changes.
- If you both changed a field, yours stays, with their value under it and a Use theirs link. Nothing is saved until you press Save again.
- A record’s lines are merged as one list, not line by line, because a save replaces the whole list. If only they changed the lines, theirs come into the form. If only you did, yours stay.
- If you both changed the lines, yours stay and nothing is saved. The notice has a Use their lines button. Saving without it puts your lines in place of theirs.
The check happens as Laravel receives the change. Two saves that arrive within a few milliseconds of each other can still both go through, as before.
Printing a record
Section titled “Printing a record”Every record’s page has a Print button, so an invoice or an order can go on paper or into a PDF, with nothing to set up for each resource. It prints the app’s name, the record’s fields and its lines with their total, in black on white whichever theme is on. The sidebar, the header, the buttons and what belongs to the record are left out, and a long table runs on from page to page with its headings on each.
To put something else on paper, or leave something out, give it print:hidden or hidden print:block, Tailwind’s classes for this, in components/dashboard/record-detail.tsx. The rest of it is in components/dashboard/print-record.css. Whatever is inside an element with the id print-area is what a page prints, so a page of your own can use the same stylesheet by importing it.
Getting dashboard fixes later
Section titled “Getting dashboard fixes later”The dashboard’s files are yours to change. nevela upgrade brings the ones you have not changed up to a newer version, and leaves the ones you changed alone. See Upgrading an app.
Changing how a resource looks
Section titled “Changing how a resource looks”Display options go in the .resource.ts file, below the generated block:
export default defineResource({ // nevela:generated:start hash=… name: "Product", fields: { /* … */ }, // nevela:generated:end defaultSort: { field: "name", direction: "asc" }, perPage: 50,});To change a page’s layout, edit the page under app/dashboard/<slug>/. For example, remove <ResourceStats /> from page.tsx to drop the numbers above the table.
The app’s name and theme
Section titled “The app’s name and theme”lib/site.ts holds the name, tagline and the text on the sign-in and home pages. Its theme picks the look: default, coral, amber, sky, mono or emerald.
A new app’s quote is Nevela’s own, from the person who made it, and its logo strip lists apps built with Nevela. Put your own in testimonial and customers. A customer can have an href, and an empty customers hides the strip.
Search engines and shared links
Section titled “Search engines and shared links”What a search engine and a shared link are told comes from lib/site.ts, through lib/seo.ts. Set NEXT_PUBLIC_SITE_URL to the address people reach the site at (https://example.com). Canonical links, the share image and the sitemap are made from it. It is built in, so redeploy after changing it.
| Every page | A title (Sign in · Your app), the site’s description, and an Open Graph and X card. |
| The share image | Drawn by app/opengraph-image.tsx: the site’s name and tagline on the theme’s brand colour. A link pasted into WhatsApp, X or LinkedIn shows it. For a designed one, put your image at app/opengraph-image.png and delete that file and app/twitter-image.tsx. |
| The icon | app/icon.tsx and app/apple-icon.tsx: the site’s first letter on the brand colour, for the browser tab and a phone’s home screen. Replace them with app/icon.png the same way. |
| robots.txt | app/robots.ts. Search engines may read the site, but not /dashboard or /api, except stored files, which link previews fetch. It names the sitemap when the app has a blog. |
| Kept out of search results | The dashboard and every page of signing in say noindex. They are still readable in robots.txt, because a page closed off there can be listed from links to it, its noindex never read. |
| Structured data | The home page says who the site is (schema.org WebSite and Organization). Each blog post is a BlogPosting, with its date, picture and publisher. |
| The sitemap | The blog’s: the home page, /blog and every post. A site with no blog is its home page, which needs none. |
In development, a shared link’s image points at localhost, so it can be looked at. Next.js gives it the site’s address in a production build.
What was removed from Flare’s app
Section titled “What was removed from Flare’s app”These parts depended on Flare’s own database, and Laravel has no endpoints for them yet: saved table views, product search, and the costs and observability pages.
Others have come back with Laravel behind them: the records-per-day chart is the insights panel above each table, the change history is the activity log, and signing in with Google and GitHub is there.
Sign-up, password reset, two-factor, passkeys and the account pages are Flare’s screens, backed by Laravel. See Authentication.
Talking to Laravel from the browser
Section titled “Talking to Laravel from the browser”Almost everything goes through server actions, which run on the web app’s server and call Laravel with the person’s token. Three things are done by the browser itself, through the web app’s own /api/… route (app/api/[...path]/route.ts), which adds the token and passes the request on:
- the relation picker’s search,
GET /api/categories?q=…, - showing stored files,
GET /api/_nevela/files/<key>, and - uploading one,
PUT /api/_nevela/uploads/<Resource>/<field>.
Nothing else that changes data is let through that route. The token stays in its httpOnly cookie either way.
lib/files.ts has fileUrl(key, "thumb"), which gives the address of a stored file or one of its renditions.