Working on Nevela
This page is for changing Nevela itself. To build an app with Nevela, use the quickstart instead.
The repository
Section titled “The repository”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.mdSet up
Section titled “Set up”git clone https://github.com/MarkColeMukisa/nevela.gitcd nevelapnpm installThe Laravel app:
cd apps/apicomposer installcp .env.example .envphp artisan key:generatephp artisan migratephp artisan nevela:userphp artisan serveThe dashboard, in a second terminal:
cd apps/webcp .env.example .env.localpnpm devapps/api installs the package from packages/laravel by path, so a change to the package is live in the app straight away.
The package
Section titled “The package”| 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:
cd packages/laravelcomposer installvendor/bin/phpunitThe app’s tests, most of which run the package inside apps/api over HTTP:
cd apps/apiphp artisan testThe create command
Section titled “The create command”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:
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.
The update command
Section titled “The update command”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:
cd packages/create-nevelanpm pack --pack-destination /tmp/templates
cd /path/to/a/test-app/apps/apiNEVELA_TEMPLATE_DIR=/tmp/templates php artisan nevela:upgrade --checkThe command looks in that folder for create-nevela-<version>.tgz before it asks npm.
The docs site
Section titled “The docs site”pnpm docs:devPages are Markdown in apps/docs/src/content/docs. The sidebar is in apps/docs/astro.config.mjs.
Tutorials
Section titled “Tutorials”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.
Before opening a pull request
Section titled “Before opening a pull request”- Add a line to
CHANGELOG.mdunder “Unreleased” if a user would notice the change. - Run the app’s tests (
php artisan testinapps/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.