Statamic Nextjs Laravel Package

Getting Started

This is a Statamic addon that bridges a Statamic (Laravel) install to a Next.js frontend — i.e. the headless/content-API layer plus whatever rendering glue the addon ships. At v0.0.2-alpha it is pre-1.0, so treat every version bump as potentially breaking.

Install

composer require morethingsdigital/statamic-nextjs:^0.0.2-alpha

Because the package only publishes alpha tags, you will likely need one of:

"minimum-stability": "alpha",
"prefer-stable": true

…or an explicit @alpha constraint. Prefer the explicit constraint so you don't silently pull alphas of unrelated dependencies.

Verify it registered

php artisan about            # Statamic addons section, if your version lists them
php artisan vendor:publish   # inspect available tags/providers

Statamic auto-discovers addons via extra.statamic in the package's composer.json; confirm the addon appears in the Control Panel under Tools → Addons before debugging anything else.

Where to look first

1. vendor/morethingsdigital/statamic-nextjs/ — read composer.json (extra.statamic, extra.laravel.providers), then the service provider. That tells you exactly which routes, config keys and view namespace exist at this tag.
2. The package's config/ and routes/ directories — this is the real API surface, not the README.
3. resources/views/ — relevant as of this release, since v0.0.2-alpha added the view namespace.

First use case

Get one content type rendering end-to-end: a Statamic collection entry → addon endpoint/response → a single Next.js page fetching it. Prove the pipe before wiring previews, caching, or nested content.

Implementation Patterns

Use the view namespace instead of editing vendor files. This is the entire substance of v0.0.2-alpha. The provider now registers its views under a namespace, so:

// Render a package view directly
return view('statamic-nextjs::some-view', compact('data'));

// Override it without touching vendor/ — mirror the path under:
// resources/views/vendor/statamic-nextjs/some-view.blade.php

Check the provider for the exact namespace string (statamic-nextjs is the convention, but confirm — a mismatch means your override silently never loads). Overrides are the supported extension point; forking the package is not.

Isolate the integration behind one client module. Keep every call to the addon's endpoints inside a single lib/statamic.ts in the Next app: one place for base URL, auth headers, error normalisation, and revalidation tags. When the alpha API shifts (it will), you change one file.

Drive base URLs from env, both directions. The Laravel side needs to know where Next lives (for preview links/redirects), and Next needs the Statamic origin. Two separate env vars, both defaulted in config, both validated at boot.

Preview/draft workflow is the pattern worth investing in early. Content editors expect to see unpublished changes. Wire the addon's preview path to a Next.js draft mode that bypasses static generation, and keep the preview token out of any client bundle.

Local development runs two servers. php artisan serve on 8000, next dev on 3000. Expect CORS configuration and absolute asset URLs — relative /assets/... paths from Statamic will resolve against the Next origin and 404.

Keep blueprints and Next components in one mental model. The common failure mode in headless Statamic is a field added in the CP that the frontend silently ignores. Decide per-collection whether you're rendering a fixed schema or a component-mapped one, and document it.

Gotchas and Tips

Alpha churn is the headline risk. v0.0.1-alpha → v0.0.2-alpha is a patch bump that changed rendering internals (view registration). Pin exact versions (0.0.2-alpha, not ^), commit the lockfile, and read the diff between tags before upgrading. There is no deprecation runway at this stage.

Clear caches after every upgrade. Statamic's view/config/route caches will happily serve the old state after a composer update:

php artisan optimize:clear
php artisan view:clear   # mandatory for the new view namespace to resolve

If statamic-nextjs:: views throw "View not found" while sitting right there in vendor/, it is almost always a stale compiled-view cache or a provider not re-registered.

Override paths must match the namespace root exactly. resources/views/vendor/{namespace}/{path} — an extra or missing directory level fails silently in favour of the vendor default, which looks like "my override is ignored" rather than an error.

Static caching will bite the API. If Statamic's static cache or a response cache is enabled, JSON responses go stale and editors report "changes not showing." Scope caching per-endpoint and check whether the addon's routes are excluded from the static cache by default.

Publish config before customising. Don't read config values out of vendor/'s copy at runtime — publish to config/statamic-nextjs.php (confirm the tag) so the values survive composer update and are visible in config:cache.

Absolute URLs for assets and Next/Image. Configure the Statamic asset container URL to a fully qualified origin, and add that origin to images.remotePatterns in next.config.js, or every image optimises into a 400.

Debugging order when content doesn't appear: (1) hit the Laravel endpoint/route directly with curl, (2) check the Statamic entry is published and in the right site/locale, (3) clear caches, (4) only then look at the Next fetch layer. Most issues are on the Laravel side.

Note the addon's stability in your own docs. If you're shipping this to a client, record the pinned version, the tag date, and the fact that upstream is a single-maintainer alpha with a sparse changelog — that's the honest risk note for handover.