Project and package manifests

Which file do you edit when you want another module, a second theme, a different server? And which files change under your hands when grim runs? Every manifest has one writer. Once you know who that is, you know whether an edit of yours will last. This tome takes the files one by one. What the version numbers and constraints in them mean is a separate subject, covered in Release trains.

grim.json is the one you write

grim create-project writes the first version. After that the file is yours, and it is one of the three files the project repository tracks. Three commands edit it for you: grim require adds to requires and themes, grim remove takes a module out of requires, and grim tune --auto writes a performance block. create-project also writes description and version. Both are labels for people, and no command reads them.

{
    "name": "shop",
    "core": "~2.5",
    "php": "^8.5",
    "requires": { "cart": "~2.5", "payments": "~2.5" },
    "themes": { "frontend": "shop-front:~2.5", "admin": "float:~2.5" },
    "docker": { "services": { "horizon": true, "scheduler": true, "reverb": false } },
    "deploy": {
        "health-timeout": 60,
        "post-deploy": ["php artisan migrate --force"],
        "environments": { "production": { "host": "203.0.113.10", "domain": "shop.example.com" } }
    }
}

A theme slot is a string or a list

A theme is written as slug:constraint. A slot with one theme stays a plain string. A slot with several is a list, ["shop-front:~2.5", "blank:~2.5"], and the first entry is the active theme. Every theme of a slot is installed. Which one the application shows is decided by THEME_FRONTEND and THEME_ADMIN in .env. grim build warns when .env names a theme the slot does not declare.

docker

deploy

grim.lock is written whole, never edited

grim install, grim update and grim require all end by writing the lock again, complete. There is no command that patches one line of it, and you should not either. Commit it with grim.json.

{
    "generated_at": "2026-03-02T09:14:07+00:00",
    "grim_cli_version": "1.4.0",
    "train": "2.5",
    "core_version": "2.5.0",
    "core_commit": "9f2c1e7a4b3d5c6e8f0a1b2c3d4e5f6a7b8c9d0e",
    "modules": {
        "cart": { "version": "2.5.3", "commit": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b", "requires": { "payments": "~2.5" } },
        "payments": { "version": "2.5.1", "commit": "7e8f9a0b1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d", "requires": [] }
    },
    "themes": { "frontend": [{ "name": "shop-front", "version": "2.5.0", "commit": "c0ffee1234567890abcdef1234567890abcdef12" }] },
    "content_hash": "sha256:5d41402abc4b2a76b9719d911017c592..."
}

modules is longer than requires in grim.json. You asked for cart. The lock also names payments, because cart requires it. grim why answers who brought a module in.

core.json comes with core

core.json sits in the project root and arrives with the grim-core release, like the rest of the skeleton. The next train overwrites it. It tells grim two things it cannot know otherwise: which train this core is, and which modules are part of core and therefore never belong in requires. Outside a project there is no core.json on disk, and create-project works from a copy bundled in grim.

{
    "name": "core",
    "version": "2.5.0",
    "php": "^8.5",
    "modules": ["admin", "auth", "common", "users"]
}

module.json describes one module

grim make:module writes the first module.json, in the module's own directory under src/. From then on you maintain three of its fields, and the release maintains two.

{
    "name": "cart",
    "namespace": "Cart",
    "version": "2.5.3",
    "type": "module",
    "provider": "CartProvider",
    "category": "commerce",
    "requires": { "payments": "~2.5" },
    "php": { "extensions": ["intl"] }
}

The resolver follows requires from module to module, and the result is the modules block of the lock. The scaffold also writes description, routes and migrations. grim does not read them. The keys minimum-core and soft-requires are gone, and grim manifest:validate fails a manifest that still carries one. Run it in the module directory before you push. It applies the required fields and shapes of this table and names every error at once. The recipe Create a module shows the file in use.

theme.json is the shortest

grim make:theme writes it into resources/themes/<type>/<name>/.

{
    "name": "shop-front",
    "version": "2.5.0",
    "type": "frontend",
    "requires-modules": ["frontend"]
}

The two module lists

Both are PHP files that return a list of provider classes, one line per module, such as Modules\Cart\CartProvider::class.

config/modules-available.php is what is installed. grim install and grim update write it again every time, from the resolved modules, taking each class name from provider in module.json. An edit does not survive.

storage/config/modules-enabled.php is what the application boots. grim install creates it as a copy of the first list, only when it does not exist, and --no-enable skips even that. After that three commands touch it, one line at a time: grim require and grim make:module add a module, grim remove takes one out. Everything else in the file is your decision, and no update brings a line back that you deleted. What grim owns in your project has the rest of that division, including why only grim.json and grim.lock are committed.