Quickstart

Quickstart

This guide takes you from an empty consumer directory to generated Laravel artifacts and a React workspace. Mettada scaffolds the manifest; you create the framework applications and then integrate the platform packages.

Prerequisites

• PHP 8.2 or newer and Composer.
• Node.js 22.23.4 or newer and npm (the documentation workspace’s locked tooling dependencies require this Node 22 patch level).
• A database supported by your Laravel application.
• This repository cloned locally, including the Mettada CLI at packages/backend-laravel/bin/mettada.

The current adapter targets Laravel 12. The generated React application uses Vite. mettada:integrate creates or updates the consumer backend’s .env with MySQL defaults (127.0.0.1:3306, user root, no password), a database name derived from the project name, and a generated APP_KEY when one is missing. It preserves existing non-default values. Make sure the MySQL database server is running and create the configured database before migrating. Never commit secrets from .env.

1. Create the consumer manifest

Run commands from the repository’s packages/ directory:

cd packages
php backend-laravel/bin/mettada mettada:init Workshop --path=Workshop

The command creates Workshop/mettada.yaml and the consumer directory structure. It does not create Laravel or Vite projects; those are framework owned. It also creates mettada and mettada.bat launchers in the consumer root. Run them from that directory to use commands without passing the project name or path. On Windows, use .\mettada.bat; on macOS/Linux, use ./mettada (or php mettada).

php backend-laravel/bin/mettada mettada:init --interactive --path=Workshop

Use a new directory. Initialization does not merge with an unrelated existing application.

2. Create the framework applications

From packages/, create the Laravel backend and React/Vite frontend in the paths configured by the manifest:

composer create-project "laravel/laravel:^12.0" Workshop/backend
npm create vite@latest Workshop/frontend -- --template react
npm install --prefix Workshop/frontend

If the manifest uses different paths, substitute them in the commands. This quickstart assumes the default backend and frontend paths.

3. Integrate and install platform dependencies

Set-Location Workshop
.\mettada.bat mettada:integrate
composer install --working-dir=backend
npm install --prefix=frontend

Integration updates the consumer dependency manifests and platform bootstrap files. It replaces the untouched Vite React starter in src/App.jsx with the Mettada platform shell; an existing custom app entry point is preserved. Re-run dependency installation after integration. If Composer cannot resolve the local efp/* path repositories, confirm the consumer was created inside this checkout and that integration completed before composer install.

Mettada keeps consumer-local feature ownership and build state in Workshop/.mettada/. For an older consumer that already has authentication, admin-seeder, or RBAC files but has no .mettada/status.json, review those files and explicitly adopt them with .\mettada.bat mettada:integrate --adopt-existing. Without adoption, existing files are preserved and integration stops rather than guessing whether they are application-owned.

4. Create an entity and workspace

Create a minimal entity spec, then a workspace linked to that entity:

.\mettada.bat mettada:entity:create Customer
.\mettada.bat mettada:workspace:create CustomerDesk --entities=Customer

The entity scaffold has no business fields yet. Edit the generated files under specs/entities/ and specs/workspaces/, using the schema reference and cookbook examples. A minimal entity shape is:

version: 1
entity:
  name: Customer
  label: Customer
  plural: Customers
meta:
  timestamps: true
fields:
  name:
    type: string
    required: true
  email:
    type: string
    required: true
    unique: true

The command-created workspace links the entity as a data source. Add the table columns, forms, filters, and actions you want; linking an entity does not infer those UI details.

5. Lint and generate

.\mettada.bat mettada:lint
.\mettada.bat mettada:sync

Lint reports schema and cross-spec reference errors without generating output. Sync reads the consumer manifest and specs and writes generated artifacts to the configured output roots. Review the diff before running migrations or deploying.

.mettada/status.json records applied feature flags, the last successfully synced feature set, and Mettada-owned feature outputs. The regenerable .mettada/build-cache.json and .mettada/metadata-snapshot.json stay local and are ignored by Git. Laravel’s own runtime caches remain under backend/bootstrap/cache.

After confirming the configured database exists, run:

php backend/artisan migrate

Start the frontend in a second terminal:

npm --prefix Workshop/frontend run dev

If you enabled authentication, configure and test the consumer’s auth integration before exposing the app. Mettada’s manifest feature flags and generated CRUD do not replace authorization checks for custom endpoints.

Optional: audited and soft-deleted entities

meta.soft_deletes adds Laravel soft-delete support and a deleted_at column. meta.auditable adds Spatie Activitylog integration. If you enable auditing, run mettada:integrate before installing Composer dependencies. Publish the Activitylog migration in the consumer backend and migrate:

php Workshop/backend/artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-migrations"
php Workshop/backend/artisan migrate

Read lifecycle metadata before enabling these flags. Existing lifecycle columns are intentionally retained by incremental rollback behavior.

Before shipping

• Re-run mettada:lint and mettada:sync after spec changes.
• Review generated migrations and API authorization.
• Add tests for domain invariants in consumer-owned code.
• Run backend tests and npm run build in the consumer frontend.
• Never run destructive database tests against a shared or production database.