create-nevela 0.1.5 → 0.3.0

package/README.md

@@ -36,21 +36,32 @@ php nevela resource Product --fields="name:string, sku:string!, price:money"
 
 That writes the Laravel code and the dashboard pages, and creates the table. `php nevela` lists everything else.
 
-## Updating an app later
+## The nevela command
+
+Install this package once and you have a `nevela` command, in every shell:
 
 ```sh
-php nevela update
+npm install -g create-nevela
 ```
 
-That updates the Laravel package, regenerates, and updates the dashboard files you have not changed. Files you changed are kept, and everything it replaces is backed up first.
+```sh
+nevela new my-app      # anywhere: create an app
+nevela update          # anywhere: update the nevela command itself
+nevela dev             # inside an app: run the API and the dashboard
+nevela upgrade         # inside an app: bring it to the latest Nevela
+```
 
-If `php` is not a command in your shell (Git Bash with Laravel Herd), or the app is an old one, run it through this package instead. It works in any shell and on an app of any age:
+As in Grit, `update` is for the tool and `upgrade` is for an app.
+
+## Upgrading an app later
 
 ```sh
-npx create-nevela update
+nevela upgrade
 ```
 
-Installed globally (`npm install -g create-nevela`), it gives you a `nevela` command: `nevela update`, `nevela dev`, `nevela status`, `nevela resource …`. See https://nevela-docs.vercel.app/guides/updating/.
+That updates the Laravel package, regenerates, and upgrades the dashboard files you have not changed. Files you changed are kept, and everything it replaces is backed up first.
+
+Without the command installed, `npx create-nevela upgrade` does the same, in any shell and on an app of any age. So does the app's own launcher, `php nevela upgrade`. See https://nevela-docs.vercel.app/guides/updating/.
 
 ## Options
 

package/index.mjs

@@ -12,10 +12,11 @@ import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
-import { latestRelease, onPackagist } from './packagist.mjs';
-import { COMMANDS, findProject, forward, update } from './project.mjs';
+import { isNewer, latestRelease, onPackagist } from './packagist.mjs';
+import { COMMANDS, findProject, forward, upgrade } from './project.mjs';
 import { shellLine, spawnCommand, windows } from './shell.mjs';
-import { newerVersion, runVersion } from './selfupdate.mjs';
+import { latestVersion, newerVersion, runVersion } from './selfupdate.mjs';
+import { globalInstall, INSTALL_COMMAND } from './tool.mjs';
 import { copyLaravelPackage, copyWebTemplate, fromRepository, templateRecord } from './template.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -41,12 +42,15 @@ const HELP = `
 
   Create a new Nevela app: a Laravel API and a Next.js dashboard.
 
-  ${bold('Create an app')}
-    pnpm create nevela <name> [options]
-    npm create nevela@latest <name> -- [options]
+  ${bold('Get the nevela command')}  (once; everything below is then this short)
+    npm install -g create-nevela
 
-  ${bold('Inside an app')}  (also as: nevela <command>, once installed with npm install -g create-nevela)
-    nevela update              Update Nevela and the dashboard to the latest version
+  ${bold('Anywhere')}
+    nevela new <name> [options]   Create an app. Without the command: pnpm create nevela <name>
+    nevela update                 Update the nevela command itself to the latest version
+
+  ${bold('Inside an app')}
+    nevela upgrade             Bring this app to the latest Nevela: the package and the dashboard
     nevela dev                 Run the API and the dashboard
     nevela status              Check versions, migrations, users and the dashboard
     nevela resource <Name> --fields="…" [--seed]
@@ -301,7 +305,7 @@ Everything else runs from this folder too, with \`php nevela\`:
 \`\`\`sh
 php nevela user        # add someone who can sign in
 php nevela status      # versions, migrations, users, and what the dashboard is talking to
-php nevela update      # update Nevela and the dashboard
+php nevela upgrade     # bring this app to the latest Nevela
 php nevela             # everything it can do
 \`\`\`
 
@@ -328,25 +332,82 @@ async function inProject(name, args) {
     fail(`"${name}" runs inside a Nevela app, and this folder isn't in one.`, `To create an app:  pnpm create nevela my-app`);
   }
   if (name === 'version') console.log(`create-nevela ${VERSION}`);
-  if (name !== 'update') process.exit(forward(project, name, args));
+  if (name !== 'upgrade') process.exit(forward(project, name, args));
 
-  // Updating is the one command that must not run on stale code itself.
+  // Upgrading is the one command that must not run on stale code itself: it is the newest
+  // installer that knows what an older app needs repaired. So even a nevela command that
+  // hasn't been updated in a while upgrades an app correctly.
   if (!process.env.NEVELA_NO_SELF_UPDATE && !fromRepository) {
     const newer = await newerVersion(VERSION);
     if (newer) {
-      const status = await runVersion(newer, ['update', ...args]);
+      const status = await runVersion(newer, ['upgrade', ...args]);
       if (status !== null) process.exit(status);
     }
   }
-  console.log(`\n  ${indigo(bold('Nevela'))} ${dim('update')}\n`);
+  console.log(`\n  ${indigo(bold('Nevela'))} ${dim('upgrade')}\n`);
   const releases = await latestRelease();
-  const status = await update(project, args, { latest: releases, say: (line) => console.log(`  ${green('✔')} ${line}`) });
+  const status = await upgrade(project, args, { latest: releases, say: (line) => console.log(`  ${green('✔')} ${line}`) });
   process.exit(status);
 }
 
+/**
+ * `nevela update`, from anywhere: update the nevela command itself.
+ *
+ * As in Grit, updating the tool and upgrading an app are two commands. This one doesn't
+ * touch any app; it ends by saying how to upgrade the one you are in, if you are in one.
+ *
+ * It returns instead of calling process.exit(): on Windows, exiting in the same moment a
+ * fetch() has just finished trips an assertion inside Node and prints a crash.
+ */
+async function updateTool(args) {
+  const project = findProject(process.cwd());
+  const install = fromRepository ? null : globalInstall(here);
+
+  if (!install) {
+    // Run through npx or `pnpm dlx`, which fetch the latest every time, started by an
+    // older nevela command that fetched this one to do its work, or a copy in a project's
+    // own node_modules. There is no installed command to update. Inside an app, "update" used to mean "upgrade this app", and
+    // instructions saying so are still around, so that is what it does.
+    if (project) {
+      console.log(`\n  ${dim(`"update" now updates the nevela command, and an app is brought up to date with "upgrade". Upgrading this app.`)}`);
+      await inProject('upgrade', args);
+    }
+    console.log(`\n  ${indigo(bold('Nevela'))} ${dim(`v${VERSION}`)}\n`);
+    console.log(`  The nevela command isn't installed on this computer, so there is nothing to update.`);
+    console.log(`  To install it:  ${bold(INSTALL_COMMAND)}`);
+    console.log(`  Then, anywhere: ${bold('nevela new my-app')}   and inside an app: ${bold('nevela upgrade')}, ${bold('nevela dev')}\n`);
+    return;
+  }
+
+  console.log(`\n  ${indigo(bold('Nevela'))} ${dim('update')}\n`);
+  const latest = await latestVersion();
+  const newer = latest !== null && isNewer(latest, VERSION) ? latest : null;
+  if (latest === null) {
+    // Not the same as being up to date, so it isn't reported as that.
+    console.log(`  ${red('!')} Couldn't reach npm to see whether there is a newer nevela than ${bold(VERSION)}. Nothing was changed.`);
+    console.log(`    Try again when you are online, or run:  ${install.command.join(' ')}`);
+    process.exitCode = 1;
+  } else if (!newer) {
+    console.log(`  ${green('✔')} nevela ${bold(VERSION)} is the latest.`);
+  } else {
+    console.log(`  Updating the nevela command ${bold(VERSION)} → ${bold(newer)} ${dim(`(${install.command.join(' ')})`)}\n`);
+    const [command, ...rest] = install.command;
+    const result = spawnCommand(command, rest, { stdio: 'inherit' });
+    if (result.error || result.status !== 0) {
+      fail(`Couldn't update the nevela command.`, `Run it yourself to see why:  ${install.command.join(' ')}`);
+    }
+    console.log(`\n  ${green('✔')} nevela is now ${bold(newer)}.`);
+  }
+  if (project) {
+    console.log(`  ${dim('This app is not changed by that. To bring it to the latest Nevela:')} ${bold('nevela upgrade')}`);
+  }
+  console.log('');
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   if (argv[0] === 'new') argv.shift();
+  else if (argv[0] === 'update') return updateTool(argv.slice(1));
   else if (COMMANDS.includes(argv[0])) await inProject(argv[0], argv.slice(1));
   const options = parseArgs(argv);
 
@@ -399,7 +460,7 @@ async function main() {
     write(path.join(web, 'pnpm-workspace.yaml'), 'allowBuilds:\n  sharp: true\n');
   }
   // Which dashboard this app started from, with a fingerprint of every file in it.
-  // `nevela update` compares against these to tell the files you changed from the ones
+  // `nevela upgrade` compares against these to tell the files you changed from the ones
   // you didn't, so an update never overwrites your work.
   write(path.join(web, '.nevela.json'), `${JSON.stringify(templateRecord(VERSION), null, 4)}\n`);
   writeRootFiles(root, { name, title, pm, admin: options.user ? ADMIN : null });
@@ -510,7 +571,7 @@ async function main() {
     console.log(`  ${dim(`That account is in this app's local database only. Add your own: ${nevela} user`)}`);
   }
   console.log(`\n  Add your first resource: ${dim(`${nevela} resource Product --fields="name:string, price:money"`)}`);
-  console.log(`  Check the app: ${dim(`${nevela} status`)}   Update it later: ${dim(`${nevela} update`)}   Everything: ${dim(nevela)}`);
+  console.log(`  Check the app: ${dim(`${nevela} status`)}   Upgrade it later: ${dim(`${nevela} upgrade`)}   Everything: ${dim(nevela)}`);
   if (nevela !== 'php nevela') {
     console.log(`\n  ${dim(`In this shell "php" isn't a command (your PHP is php.bat), so use ${nevela}. In PowerShell, php nevela works too.`)}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevela",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Create a new Nevela app: a Laravel API and a Next.js dashboard from one resource description.",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "selfupdate.mjs",
     "shell.mjs",
     "project.mjs",
+    "tool.mjs",
     "template",
     "LICENSE"
   ],

package/project.mjs

@@ -2,15 +2,16 @@
 //
 // The same commands as the app's own `php nevela`, but started from Node. That matters in
 // shells where typing `php` doesn't work (Git Bash with Laravel Herd, where PHP is
-// php.bat), and for `update`, which has to work on an app of any age, including one from
+// php.bat), and for `upgrade`, which has to work on an app of any age, including one from
 // before the app had a launcher at all.
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { isNewer, satisfiesCaret } from './packagist.mjs';
 import { spawnCommand } from './shell.mjs';
 
 /** What `nevela <name>` runs: these go to `php artisan nevela:<name>`. */
-const NEVELA = ['update', 'dev', 'status', 'version', 'resource', 'generate', 'seed', 'user'];
+const NEVELA = ['upgrade', 'dev', 'status', 'version', 'resource', 'generate', 'seed', 'user'];
 /** These go to the artisan command of the same name. */
 const ARTISAN = ['migrate', 'tinker', 'test', 'serve'];
 
@@ -64,6 +65,16 @@ export function repairManifest(manifest, latest) {
   if (typeof current === 'string' && /^\d+\.\d+(\.\d+)?$/.test(current)) {
     manifest.require['nevela/laravel'] = caret ?? `^${current.split('.').slice(0, 2).join('.')}`;
     repairs.push(`"nevela/laravel": "${current}" pinned one exact version; it is now "${manifest.require['nevela/laravel']}"`);
+    return repairs;
+  }
+
+  // Below 1.0 a caret holds the minor version: "^0.1" never reaches 0.2.0, so an update
+  // would finish having changed nothing. Updating is asking for the newest, so the range
+  // is moved to the one that has it.
+  const range = typeof current === 'string' ? /^\^(\d+)\.(\d+)(?:\.\d+)?$/.exec(current) : null;
+  if (range && caret && caret !== current && !satisfiesCaret(latest, [Number(range[1]), Number(range[2])]) && isNewer(latest, `${range[1]}.${range[2]}.0`)) {
+    manifest.require['nevela/laravel'] = caret;
+    repairs.push(`"nevela/laravel": "${current}" doesn't reach ${latest}; it is now "${caret}"`);
   }
   return repairs;
 }
@@ -97,8 +108,13 @@ function inApp(project, command, args) {
   return result.status ?? 1;
 }
 
-/** `nevela update`: bring an app of any age to the latest Nevela. */
-export async function update(project, args, { latest, say }) {
+/**
+ * `nevela upgrade`: bring an app of any age to the latest Nevela.
+ *
+ * The artisan command is called by its older name, nevela:update, which every version of
+ * the package answers to (from 0.3.0 it is an alias of nevela:upgrade).
+ */
+export async function upgrade(project, args, { latest, say }) {
   const check = args.includes('--check');
   const manifestFile = path.join(project.api, 'composer.json');
   const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));

package/selfupdate.mjs

@@ -14,17 +14,27 @@ import { isNewer } from './packagist.mjs';
 
 const REGISTRY = 'https://registry.npmjs.org/create-nevela';
 
-/** The newest create-nevela on npm when it is newer than `current`, else null. Never throws. */
-export async function newerVersion(current) {
+/** The newest create-nevela on npm, or null when npm couldn't be asked. Never throws. */
+export async function latestVersion() {
   try {
     const response = await fetch(`${REGISTRY}/latest`, { signal: AbortSignal.timeout(4000) });
     const latest = (await response.json()).version;
-    return isNewer(latest, current) ? latest : null;
+    return typeof latest === 'string' && /^\d+\.\d+\.\d+$/.test(latest) ? latest : null;
   } catch {
     return null;
   }
 }
 
+/**
+ * The newest create-nevela on npm when it is newer than `current`, else null. Never throws.
+ * Null also when npm couldn't be asked: callers that only want to run the newest carry on
+ * with what they have.
+ */
+export async function newerVersion(current) {
+  const latest = await latestVersion();
+  return latest !== null && isNewer(latest, current) ? latest : null;
+}
+
 /**
  * Unpack a .tar (already gunzipped) into `dir`. Enough of the format for an npm tarball:
  * regular files and directories, with the long-name extensions npm uses.

package/template/laravel/README.md

@@ -43,7 +43,7 @@ Needs PHP 8.2 or newer and Laravel 11, 12 or 13.
 | `nevela:generate` | Regenerate after changing a descriptor. Your own code is kept. |
 | `nevela:seed` | Fill a resource with plausible records, and print how long it took. |
 | `nevela:user` | Create someone who can sign in. |
-| `nevela:update` | Update the package, the generated code and the dashboard. |
+| `nevela:upgrade` | Bring the app to the latest Nevela: the package, the generated code and the dashboard. `nevela:update` is its older name and still works. |
 
 Full documentation: https://nevela-docs.vercel.app
 

package/template/laravel/composer.json

@@ -1,59 +1,61 @@
-{
-    "name": "nevela/laravel",
-    "description": "Nevela for Laravel: describe a resource once and generate its model, migration, validation, policy and REST API, plus the Next.js dashboard screens for it.",
-    "type": "library",
-    "license": "MIT",
-    "keywords": [
-        "laravel",
-        "nevela",
-        "generator",
-        "crud",
-        "rest-api",
-        "nextjs",
-        "dashboard",
-        "scaffold"
-    ],
-    "homepage": "https://nevela-docs.vercel.app",
-    "authors": [
-        {
-            "name": "Mark Cole MUKISA",
-            "homepage": "https://github.com/MarkColeMukisa"
-        }
-    ],
-    "support": {
-        "issues": "https://github.com/MarkColeMukisa/nevela/issues",
-        "source": "https://github.com/MarkColeMukisa/nevela",
-        "docs": "https://nevela-docs.vercel.app"
-    },
-    "require": {
-        "php": "^8.2",
-        "illuminate/support": "^11.0|^12.0|^13.0",
-        "illuminate/database": "^11.17|^12.0|^13.0",
-        "illuminate/http": "^11.0|^12.0|^13.0",
-        "illuminate/console": "^11.0|^12.0|^13.0"
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^11.0"
-    },
-    "suggest": {
-        "laravel/sanctum": "Required for the token sign-in endpoints and the default auth:sanctum middleware (php artisan install:api)."
-    },
-    "autoload": {
-        "psr-4": {
-            "Nevela\\Laravel\\": "src/"
-        }
-    },
-    "autoload-dev": {
-        "psr-4": {
-            "Nevela\\Laravel\\Tests\\": "tests/"
-        }
-    },
-    "extra": {
-        "laravel": {
-            "providers": [
-                "Nevela\\Laravel\\NevelaServiceProvider"
-            ]
-        }
-    },
-    "minimum-stability": "stable"
-}
+{
+    "name": "nevela/laravel",
+    "description": "Nevela for Laravel: describe a resource once and generate its model, migration, validation, policy and REST API, plus the Next.js dashboard screens for it.",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "laravel",
+        "nevela",
+        "generator",
+        "crud",
+        "rest-api",
+        "nextjs",
+        "dashboard",
+        "scaffold"
+    ],
+    "homepage": "https://nevela-docs.vercel.app",
+    "authors": [
+        {
+            "name": "Mark Cole MUKISA",
+            "homepage": "https://github.com/MarkColeMukisa"
+        }
+    ],
+    "support": {
+        "issues": "https://github.com/MarkColeMukisa/nevela/issues",
+        "source": "https://github.com/MarkColeMukisa/nevela",
+        "docs": "https://nevela-docs.vercel.app"
+    },
+    "require": {
+        "php": "^8.2",
+        "illuminate/support": "^11.0|^12.0|^13.0",
+        "illuminate/database": "^11.17|^12.0|^13.0",
+        "illuminate/http": "^11.0|^12.0|^13.0",
+        "illuminate/console": "^11.0|^12.0|^13.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^11.0"
+    },
+    "suggest": {
+        "laravel/sanctum": "Required for the token sign-in endpoints and the default auth:sanctum middleware (php artisan install:api).",
+        "ext-gd": "Optimises uploaded images: resizing, WebP and renditions. Without it images are stored as uploaded.",
+        "ext-exif": "Turns phone photos the right way up before their metadata is removed."
+    },
+    "autoload": {
+        "psr-4": {
+            "Nevela\\Laravel\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Nevela\\Laravel\\Tests\\": "tests/"
+        }
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Nevela\\Laravel\\NevelaServiceProvider"
+            ]
+        }
+    },
+    "minimum-stability": "stable"
+}

package/template/laravel/config/nevela.php

@@ -33,4 +33,74 @@ return [
     /* List defaults, matching Flare's client. */
     'per_page' => 25,
     'max_per_page' => 100,
+
+    /*
+    | File and image fields (image:image, manual:file(pdf)).
+    |
+    | Files go on a disk from config/filesystems.php and are handed out by Nevela's own
+    | route, GET {prefix}/_nevela/files/{key}, so nothing needs linking or publishing. Keys
+    | are unguessable, but anyone who has one can fetch the file: don't use these fields
+    | for documents that must stay private. If a CDN or your web server serves the disk,
+    | put its address in NEVELA_UPLOADS_URL and the API's links point there.
+    */
+    'uploads' => [
+        'disk' => env('NEVELA_UPLOADS_DISK', 'public'),
+        'url' => env('NEVELA_UPLOADS_URL'),
+
+        /* Where untouched originals are kept, so an image can be optimised again later. Never served. */
+        'originals_disk' => env('NEVELA_ORIGINALS_DISK', 'local'),
+
+        /* The largest file a field takes. */
+        'max_bytes' => 10 * 1024 * 1024,
+
+        /* Memory allowed while an image is being optimised: a phone photo needs more than PHP's usual 128M. */
+        'memory' => '512M',
+
+        /*
+        | How images are optimised. Every image field uses "default" unless it names another:
+        | image:image(product). A profile only says what differs from the default.
+        |
+        |   max         [width, height] the stored image fits inside. Add 'crop' to fill it exactly.
+        |   quality     1 to 100.
+        |   format      auto, webp, jpeg, png or avif. Auto keeps transparency and otherwise
+        |               picks the smallest.
+        |   renditions  extra sizes made alongside, by name. Ask for one by putting its name
+        |               before the extension: kettle.webp → kettle.thumb.webp
+        |   keep_original  keep the untouched upload on the originals disk.
+        |   on_error    store_original (keep the upload as it came) or reject.
+        |   max_pixels  refuse anything that would decode to more than this.
+        */
+        'profiles' => [
+            'default' => [
+                'max' => [1600, 1600],
+                'quality' => 82,
+                'format' => 'auto',
+                'renditions' => ['thumb' => [400, 400, 'crop']],
+                'keep_original' => true,
+                'on_error' => 'store_original',
+                'max_pixels' => 50_000_000,
+            ],
+
+            // A product photograph: smaller than the default, because a catalogue page shows a dozen at once.
+            'product' => [
+                'max' => [1000, 1000],
+                'quality' => 80,
+                'renditions' => ['thumb' => [300, 300, 'crop'], 'card' => [600, 600]],
+            ],
+
+            // Always square and always small, so it crops: a portrait in a round frame shouldn't letterbox.
+            'avatar' => [
+                'max' => [400, 400, 'crop'],
+                'quality' => 85,
+                'renditions' => ['thumb' => [80, 80, 'crop']],
+                'keep_original' => false,
+            ],
+
+            // A hero or cover image, where width matters more than total pixels.
+            'cover' => [
+                'max' => [2400, 1200],
+                'renditions' => ['thumb' => [600, 300, 'crop']],
+            ],
+        ],
+    ],
 ];

package/template/laravel/database/migrations/2026_10_04_000000_create_nevela_uploads_table.php

@@ -0,0 +1,38 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+// What Nevela knows about each uploaded file: where it is, how big it is, and for an
+// image, its dimensions and the smaller renditions made from it.
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('nevela_uploads', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->string('key', 512)->unique();
+            $table->string('disk');
+            $table->string('resource')->index();
+            $table->string('field');
+            $table->string('name');
+            $table->string('mime');
+            $table->unsignedBigInteger('size');
+            $table->unsignedInteger('width')->nullable();
+            $table->unsignedInteger('height')->nullable();
+            $table->json('renditions')->nullable();
+            $table->string('profile')->nullable();
+            $table->boolean('optimised')->default(false);
+            $table->string('original_key', 512)->nullable();
+            $table->unsignedBigInteger('original_size')->nullable();
+            $table->string('uploaded_by')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('nevela_uploads');
+    }
+};

package/template/laravel/src/Console/GenerateCommand.php

@@ -61,9 +61,32 @@ final class GenerateCommand extends Command
     public static function generate(Command $command, array $targets, array $all, bool $force): int
     {
         $generator = new ResourceGenerator;
-        $files = [];
+        $byName = [];
+        foreach ($all as $descriptor) {
+            $byName[$descriptor->name] = $descriptor;
+        }
+
+        // A relation is written on both ends, so the resource a new one points at is
+        // regenerated with it: Category gains its products when Product arrives.
+        $queue = [];
         foreach ($targets as $descriptor) {
-            array_push($files, ...$generator->forResource($descriptor));
+            $queue[$descriptor->name] = $descriptor;
+            foreach ($descriptor->fields as $field) {
+                if ($field->kind !== 'belongsTo') {
+                    continue;
+                }
+                if (! isset($byName[$field->target])) {
+                    $command->components->error("{$descriptor->name}.{$field->name} belongs to {$field->target}, which doesn't exist yet. Create it first: php artisan nevela:resource {$field->target} --fields=\"name:string\"");
+
+                    return self::FAILURE;
+                }
+                $queue[$field->target] ??= $byName[$field->target];
+            }
+        }
+
+        $files = [];
+        foreach ($queue as $descriptor) {
+            array_push($files, ...$generator->forResource($descriptor, null, $all));
         }
         $files[] = $generator->routes($all);
         $files[] = $generator->registry($all);

package/template/laravel/src/Console/MakeResourceCommand.php

@@ -43,6 +43,14 @@ final class MakeResourceCommand extends Command
 
             return self::FAILURE;
         }
+        // Checked before anything is written: a relation needs the resource it points at.
+        foreach ($descriptor->fields as $field) {
+            if ($field->kind === 'belongsTo' && $field->target !== $descriptor->name && ! is_file($dir.DIRECTORY_SEPARATOR.Naming::kebab((string) $field->target).'.json')) {
+                $this->components->error("{$field->name} belongs to {$field->target}, which doesn't exist yet. Create it first: php artisan nevela:resource {$field->target} --fields=\"name:string\"");
+
+                return self::FAILURE;
+            }
+        }
         if (! is_dir($dir)) {
             mkdir($dir, 0775, true);
         }