Skip to content
Nevela 0.33.1: New: customers get a shop in the mobile app, each sees only their own orders, and an administrator manages people and roles from the phone. Build it in the new drinks-app tutorial.A drinks app on the phone

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.

  1. The browser asks the Next.js server for a page or submits a form.
  2. The Next.js server reads the visitor’s token from an httpOnly cookie.
  3. It calls Laravel with that token as a Bearer header.
  4. Laravel validates, checks its policy, reads or writes, and answers.
  5. 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.