Capell Skeleton Laravel Package

Getting Started

The skeleton is a template, not a library. You consume it once, then you own every file. Plan your workflow around that: composer update will never bring you skeleton improvements, only upstream package changes.

Bootstrap a new project

composer create-project capell-app/capell-skeleton my-site
cd my-site
cp .env.example .env
php artisan key:generate
# set DB_* in .env
php artisan migrate

Then the step that trips people up — the Foundation theme's frontend CSS is produced by a Node build, and the Node dependencies it needs are only installed by the documented post-install step (this is exactly what v1.0.4 patches):

node -v            # pin this; see Gotchas
npm ci             # or npm install on a first run
npm run build      # whatever the skeleton's package.json exposes
php artisan storage:link
php artisan serve

If you skip the npm step, the app boots fine and the theme renders unstyled — a confusing failure mode because nothing errors.

Where to look first, in order

1. composer.json — which capell-app/* packages are wired in and at what constraints. This tells you what the actual CMS surface is versus what's skeleton glue.
2. config/ — Capell config plus anything publishable from the underlying packages (php artisan vendor:publish --tag=capell-config if the skeleton didn't already ship it).
3. app/Providers/ and bootstrap/providers.php — how Capell is registered and where you add your own.
4. The theme directory (Foundation-generated) — locate it before you write a single line of CSS, because it is generated, not authored.
5. routes/web.php and the frontend catch-all — how content URLs resolve to theme views.

First use case to prove out: create one content type, one entry, and render it at a public URL through the theme. That single vertical slice exercises the admin, the model layer, the routing, and the asset pipeline — the four things most likely to be misconfigured. Do it in a scratch repo, not in the real project.

Implementation Patterns

Scaffold once, then track upstream by diff

Because this is a skeleton, there is no upgrade path. Adopt this instead:

git remote add skeleton https://github.com/capell-app/capell-skeleton.git
git fetch skeleton --tags
git diff v1.0.4..v1.0.5 -- package.json config/ app/Providers/

Read the diff, cherry-pick what applies. Never merge. Maintain a SKELETON.md in your repo recording which tag you started from and which upstream commits you hand-applied — otherwise the next upgrade is archaeology.

Separate the two build pipelines

You will almost certainly end up with two frontend builds: your app's own (Vite, typically) and the theme's Foundation CSS build. Keep them distinct and ordered explicitly rather than hoping a single npm run build covers both:

{
  "scripts": {
    "build": "npm run build:theme && npm run build:app",
    "build:theme": "npm --prefix resources/themes/foundation run build",
    "build:app": "vite build"
  }
}

Then make the PHP side depend on it deterministically. A composer.json post-install script that shells out to npm is convenient locally and a footgun in CI — prefer CI steps that run in a known order:

- run: npm ci
- run: npm run build
- run: composer install --no-dev --optimize-autoloader
- run: php artisan migrate --force

Own the theme, don't regenerate it

Treat the generated Foundation theme as a starting point you fork. Copy it to a theme directory you own, commit the generated output, and add your overrides in a separate layer (custom properties, an extra stylesheet loaded after the Foundation output). This keeps your design changes out of the regeneration blast radius if you ever re-run the generator.

Load order matters — anything you add must come after the Foundation CSS, or you'll be fighting specificity with !important.

Config through env, cached in production

Capell config is Laravel config. Keep every environment-varying value in .env and reference it from config/, then cache in production. If you instead edit published config files directly per environment, config:cache will silently serve the wrong values and you'll debug the wrong layer.

Integrate into an existing app by installing packages, not copying a skeleton

If you already have a Laravel app, do not copy the skeleton's files over it — you will clobber bootstrap/app.php, providers, and asset config. Instead, require the underlying capell-app/* packages individually and work through their publish tags, using the skeleton repo as a reference implementation to read. The skeleton's value in this mode is showing you the correct wiring, not providing files.

Smoke-test the build, not just the app

A green build that emits no CSS is the characteristic failure here. Assert on it:

public function test_theme_css_is_present(): void
{
    $this->get('/')->assertOk()->assertSee('foundation', false);
}

Better still, hash the built CSS in CI and fail if it changes without a corresponding source change. It costs ten minutes to set up and catches the entire class of "build succeeded, site is unstyled" incidents.

Gotchas and Tips

The missing-Node-dependency trap. v1.0.4 exists solely because the documented post-install build failed without an explicit Node dependency install. This tells you the install path is not covered by the package's own CI. Consequence: assume the install docs are unverified for your environment and budget a clean-room run-through before you commit to a deploy model. Record every deviation — that transcript is your runbook.

Pin Node, don't inherit it. The support matrix for Node versions is not stated. Put an .nvmrc and an explicit FROM node:XX in your Dockerfile. Relying on a runner's default Node means a base-image bump can break your deploy months later with no change on your side.

Commit a lockfile. If the theme scaffold ships without one, generate and commit it immediately, then use npm ci everywhere. Unpinned transitive dependencies make "worked yesterday, broken today" a routine occurrence and make build failures unattributable.

Build in CI, never on the production host. The documented post-install build is a deploy-time hazard: if it runs on the app server and Node isn't there, your release fails after the code is already in place. Compile in CI, ship the artifacts, and keep production Node-free.

Decide build-time vs. runtime early. Establish whether the package ships precompiled CSS and whether your build replaces or merely unblocks it. The answer determines who owns the failure — developer, CI, or release engineering. If themes ever compile per-tenant rather than per-deploy, that cost scales with tenant count and must be precomputed.

Config and route caching hide CMS changes. After adding content types, routes, or config in a cached environment, php artisan config:clear route:clear view:clear before concluding something is broken. Most "my new content type 404s" reports are cache, not code.

Asset 404s after deploy. Themes usually resolve assets through a manifest. If storage:link wasn't run or the manifest is stale, you get 404s that look like routing bugs. Check the manifest file exists and its hashes match the deployed assets.

Don't fork the core packages. Extend through the documented seams — custom blocks/content types, view overrides, your own service providers, event listeners. Every line you patch into vendor/ is a line you re-patch on the next composer update, and with a young 1.x package those come often.

Version semantics are loose. A documentation/install fix landed as a patch release. Read changelogs for 1.0.x releases rather than assuming "patch = no action needed" — you may need to change your pipeline. Pin exact versions and upgrade deliberately.

Debugging order for a broken frontend

1. Is the built CSS present on disk and in the manifest? (build problem)
2. Is it being served and linked in the rendered HTML? (view/asset problem)
3. Is your override CSS loading after Foundation? (cascade problem)
4. Is config/route/view cache stale? (Laravel problem)

Work in that order; it front-loads the two most common causes and stops you debugging application code for an asset pipeline issue.

Organisational, but real: the theme build sits between backend and frontend ownership and is the most likely thing to fall through the gap. Name an owner for it on day one, and keep the runbook in the repo rather than in a chat thread — upstream support bandwidth for this package appears low, so self-sufficiency is the plan.