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

Quickstart

This page takes you from an empty folder to a running dashboard with one resource in it.

  • PHP 8.3 or newer, with Composer
  • Node.js 20 or newer
  • Nothing else. The database is SQLite by default, which needs no setup.

On a new computer, or if you aren’t sure you have them, start with Set up your computer: what to install on macOS, Windows and Linux, in order, and how to check each one.

Terminal window
npm install -g create-nevela

Once, on your computer. Every command on this site is then nevela and a word, in any shell. nevela --version says which version you have, and nevela update brings it up to date.

You can skip this: pnpm create nevela my-app (or npm create nevela@latest my-app) creates an app without installing anything, and inside an app php nevela dev does what nevela dev does. Without the nevela command lists the longer forms.

Terminal window
nevela new my-app

Leave the name off and it asks for one. It asks nothing else, and does the setup for you. Each thing it makes gets a line, and the line in hand shows what it is on: the package that just landed, the table being created.

✔ Project folder my-app 3ms
✔ Dashboard Next.js · 208 files 174ms
✔ Laravel app laravel/laravel v13.11.0 6.2s
✔ Laravel packages 119 packages 1m 12s
✔ Environment .env · SQLite · API tokens 76ms
✔ Database 16 migrations 24.8s
✔ Administrator admin@example.com
✔ Sample users 2 editors · 8 users
✔ Blog Post resource · 3 posts · /blog
✔ Dashboard packages pnpm · 140 packages 36.0s
✔ Git repository git init 412ms
Created my-app Laravel API · dashboard · blog · 2m 26s
Then open http://localhost:3000/sign-in and sign in with:
Email admin@example.com
Password password

That timing is from a Windows laptop with antivirus running, which is the slow case. Most of it is unpacking Laravel’s packages; the dashboard’s packages download at the same time. On Linux and macOS it is usually under a minute.

To make it quicker still, leave out the development packages (PHPUnit, Pint and the like) and add them when you need them:

Terminal window
nevela new my-app --fast

About a third quicker. Add them later with composer install in apps/api.

A new app is always created by the newest installer. If the nevela command you have is older, it fetches the latest itself before doing anything.

The dashboard’s packages are installed with pnpm when you have it, and npm otherwise. --pm picks another.

You get this:

my-app/
├─ apps/api/ a Laravel app with Sanctum and Nevela installed
├─ apps/web/ the Next.js dashboard, pointed at the API
└─ nevela the app's own launcher: php nevela does what nevela does

Project structure explains what is where.

Terminal window
cd my-app
nevela dev

That starts the Laravel API and the dashboard together and prints where each one is: normally http://127.0.0.1:8000 and http://localhost:3000. If another program is already using a port, it takes the next free one and tells the dashboard, so the two always find each other.

Open http://localhost:3000/sign-in and sign in with the starter account:

Email admin@example.com
Password password

That account is the administrator. Ten sample users are there too, with the same password: two editors and eight users. Open Users in the sidebar to see them and Roles to see what each may do, or sign in as amara.okafor@example.com (an editor) or sofia.martinez@example.com (a user) to see the dashboard as they do. Users, roles and permissions has the rest.

The app also has a blog. Open http://localhost:3000/blog: a post for each of Nevela’s tutorials is on it, and the newest three are on the home page, and Posts in the dashboard is where they are written. The blog says how it works and how to change it, and nevela new my-app --no-blog leaves it out.

From anywhere inside my-app:

Terminal window
nevela resource Contact --fields="name:string, email:email!, company:string?, status:enum(lead|customer)" --icon=users

That one command writes the Laravel code and the dashboard pages, and creates the table. Reload the dashboard. Contacts is in the sidebar, with a table, a form and a detail page.

To have something to look at:

Terminal window
nevela seed Contact --count=1000

Run nevela on its own to see everything it can do.

The new resource came with four permissions: contacts.view, contacts.create, contacts.edit and contacts.delete. The administrator has them all, and so do the two sample editors. The sample users have none, so Contacts isn’t in their sidebar.

Open Roles to change what a role allows or to make one of your own, and Users to give it to someone. For a rule that depends on the record itself, such as “only its owner may edit it”, open apps/api/app/Policies/ContactPolicy.php: the file is generated once and is yours from then on. See Users, roles and permissions.

“PHP isn’t installed” or “Composer isn’t installed”. The command checks for both before it starts. Install them, open a new terminal so they are on your PATH, and run it again.

Not sure what state the app is in. Ask it:

Terminal window
nevela status

It lists the Nevela version, which migrations have run and which are pending, how many people can sign in, each resource and its record count, and whether the dashboard is reaching this app’s API. Anything wrong is marked in red with the command that fixes it.

Sign-in says the address “is answered by a different program”. Another program on your machine, often another Laravel project’s php artisan serve, already had port 8000, and the dashboard reached that instead of this app. Start both with nevela dev, which checks the port first and moves to a free one.

“Can’t reach the server” on the sign-in page. The API is not running. Start it with nevela dev.

“nevela: command not found”. The command isn’t installed, or your terminal was open before it was. Run npm install -g create-nevela and open a new terminal. Without it, pnpm nevela dev works inside an app in every shell.

“php: command not found” in Git Bash. With Laravel Herd on Windows, PHP is php.bat, and Git Bash does not run that when you type php. The nevela command is not affected: it finds PHP itself. Only the longer form php nevela … needs PowerShell there.

nevela update seems to change nothing. The command is probably installed twice. nevela --version says so and prints what removes the extra copy. See If an update seems to change nothing.

The folder already exists. The command refuses to write into a folder that has files in it. Pick another name or remove the folder.

Option Meaning
--pm <pnpm|npm|yarn|bun> Package manager for the dashboard. Default: pnpm when you have it, and npm otherwise.
--no-install Don’t install the dashboard’s dependencies.
--fast Leave out PHPUnit, Pint and Laravel’s other development packages. About a third quicker.
--no-user Don’t create the starter account, or the sample users.
--no-sample-users Create the administrator only, without the ten sample users.
--no-blog Leave out the blog: the Post resource, its sample posts and /blog.
--mobile Add a mobile app in apps/mobile: Expo, for iOS and Android, signing in to the same API.
--no-git Don’t run git init.
--bundled-package Use the copy of nevela/laravel inside the installer instead of the release on Packagist.
-y, --yes Ask nothing. Only the app name is ever asked for, and only if you leave it off.

Through npm’s create, put options after --: npm create nevela@latest my-app -- --no-install.