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

Working on Nevela

This page is for changing Nevela itself. To build an app with Nevela, use the quickstart instead.

nevela/
├─ apps/
│ ├─ api/ a Laravel app used to develop and test the package
│ ├─ web/ the dashboard. Also the template new apps are created from
│ └─ docs/ this documentation site
├─ packages/
│ ├─ laravel/ the nevela/laravel Composer package
│ └─ create-nevela/ the `pnpm create nevela` command
├─ scripts/ the release and split scripts
└─ CHANGELOG.md
Terminal window
git clone https://github.com/MarkColeMukisa/nevela.git
cd nevela
pnpm install

The Laravel app:

Terminal window
cd apps/api
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan nevela:user
php artisan serve

The dashboard, in a second terminal:

Terminal window
cd apps/web
cp .env.example .env.local
pnpm dev

apps/api installs the package from packages/laravel by path, so a change to the package is live in the app straight away.

Path What it holds
src/Console/ The artisan commands.
src/Generator/ The templates, and the writer that keeps people’s code.
src/Http/ The base form request, the error format, and the controllers for sign-in, users and roles, uploads, actions, the trash, public forms, notifications and activity.
src/Support/ Descriptors, fields, list-query parsing and seed values. Plain PHP, tested without Laravel.
everything else Sign-in, roles, files, the trash, public forms, notifications and activity. The package map has a line for each folder.

The package’s unit tests:

Terminal window
cd packages/laravel
composer install
vendor/bin/phpunit

The app’s tests, most of which run the package inside apps/api over HTTP:

Terminal window
cd apps/api
php artisan test

packages/create-nevela has no template of its own in the repository. Run from here, it copies apps/web and packages/laravel directly, leaving out the example resources. When it is packed for npm, build-template.mjs copies those same folders into template/.

So a change to apps/web is a change to what new apps get.

Try it against your working copy, from any folder outside the repository:

Terminal window
node /path/to/nevela/packages/create-nevela/index.mjs test-app --bundled-package

--bundled-package makes the new app use packages/laravel from your working copy. Without it, the app installs the last release from Packagist and your changes to the package are not in it.

nevela:upgrade normally downloads dashboard templates from npm. To test it against your working copy, pack the installer into a folder and point the command at it:

Terminal window
cd packages/create-nevela
npm pack --pack-destination /tmp/templates
cd /path/to/a/test-app/apps/api
NEVELA_TEMPLATE_DIR=/tmp/templates php artisan nevela:upgrade --check

The command looks in that folder for create-nevela-<version>.tgz before it asks npm.

Terminal window
pnpm docs:dev

Pages are Markdown in apps/docs/src/content/docs. The sidebar is in apps/docs/astro.config.mjs.

Each tutorial has its steps in examples/<name>/: steps.sh runs its nevela commands in a new app, and files/ holds what it has you write. CI makes an app for each and runs them, then builds the dashboard. scripts/tutorials.test.mjs (in pnpm test:docs) checks that every command before the script’s # Checks line, and every file, is on the tutorial’s page as it is. Change a tutorial and its script together.

To run one yourself, from the top of a new app: bash /path/to/nevela/examples/contacts/steps.sh. With Laravel Herd in Git Bash, put PHP=php.bat in front.

A new app’s blog starts with a post for each tutorial in apps/docs/src/tutorials.ts that is out. The package carries a copy, packages/laravel/resources/tutorials/: the words, and each cover at 800 pixels wide and 60 KB at most. After adding or changing a tutorial or its cover, run node scripts/tutorial-posts.mjs (it needs PHP with GD; PHP=php.bat with Herd in Git Bash). pnpm test:docs fails while the copy is behind.

  • Add a line to CHANGELOG.md under “Unreleased” if a user would notice the change.
  • Run the app’s tests (php artisan test in apps/api), and the package tests if you changed the package.
  • CI runs the package tests on PHP 8.3 and 8.4, the app’s feature tests on SQLite and on Postgres, checks the generated code is up to date, builds the dashboard and the docs, and creates a new app with create-nevela, adds every kind of resource to it and builds it. See How it is tested.

packages/laravel is also published on its own, from a read-only copy at MarkColeMukisa/nevela-laravel. Change it here, never there.

Releasing covers versions and publishing.