Repository files navigation

A minimal, production-ready starter forNext.js 15 andCraft CMS projects. Check out thefeatures, ordive right in!

This project assumes you have our recommended development environmentDDEV installed and up-to-date.

1. Clone this repository, and move into the new directory:

   git clone https://github.com/craftcms/starter-next.git# ...cd starter-next

2. (Optional) Adjust the DDEV project name and domains. Seethis section for more information.

3. Set up the Craft CMS backend:

   ddev composer installddev craft install

   Write down the username and password you choose, during installation. You’ll need it tolog in to the control panel.

4. Generate a token for theGuestbook GraphQL schema:

   # Display a list of schemas and UUIDs:ddev craft graphql/list-schemas# Use the “Guestbook” schema ID to generate a token:ddev craft graphql/create-token c7d2eb61-cdde-4a76-88a9-eb30ddcf155b

   (TheGuestbook schema is automatically created with the appropriate permissions viaProject Config as Craft is installed, buttokens are unique to each environment.)

5. Add required Next.js configuration:

   • Copyfrontend/.env.example tofrontend/.env;
   • Populate theGRAPHQL_TOKEN variable with the token you just generated;

6. Install front-end dependencies and start the Next.js development server:

   ddev fe npm installddev fe npm run dev

Runddev launch to open the front end in your default browser, or visithttps://starter-next.ddev.site.

The Craftcontrol panel is available athttps://api.starter-next.ddev.site/admin. Log in with the username and password you created during installation!

This project includes basic support for a handful of Craft’s best features, in a tidy headless package built onNext.js 15.

Next.js communicates with Craft’s built-inGraphQL API to query posts and pages, and create (or “mutate”) guestbook entries.

Craft’s live preview works just as you’d expect. You can even copy a secure, sharable URL to any draft.

The blog, category feeds, and the guestbook are neatly paginated in a way that matches Craft’s native handling. Progress through a set of paginated results is reflected in the URL and your browser’s navigation history.

We’ve split the project directory into two folders,backend/ andfrontend/, to better demonstrate the boundaries of Craft and Next.js, respectively. Some configuration needs to be transcribed between the spaces to ensure each half understands where the other lives!

There is no.gitignore at the root of the project—instead, each system maintains its own relatively-vanilla file (backend/.gitignore andfrontend/.gitignore).

Thebackend/ directory is predominantly a standard Craft installation, soits structure should be familiar. Craft is configured to run inheadless mode, which means it doesn’t perform any element routing, nor template rendering—in fact, it will only respond tocontrol panel,action, and static asset requests (like any images you might upload).

Craft uses thePRIMARY_SITE_URL environment variable (automatically set by DDEV) to generate fully-qualified URLs for front-end pages, and theCRAFT_BASE_CP_URL (predefined inbackend/.env) to build control panel and asset URLs.

Next.js lives in thefrontend/ directory. All NPM commands should be executed here—as a convenience, we’ve included a custom DDEV command (.ddev/commands/web/fe) that ensures tasks are run in the appropriate directory:

• ddev fe npm install → Moves intofrontend/, then executesnpm install;
• ddev fe npm run dev → Moves intofrontend/, then executes the user-defineddev script;

Seefrontend/next.config.js tocustomize Next.js, or read about the rest of itsproject structure.

Routing is handled primarily via theapp/ directory, and GraphQL queries are centralized inqueries/.

If you want to compress the GraphQL query feedback loop, open up the Craft control panel and clickGraphQL in the main navigation, then chooseGraphiQL.Read more about the GraphQL IDE in the Craft documentation.

The DDEV configuration files shipped with this project use a specific pair of URLs for the Next.js front end and Craft back end:

• Front end:https://starter-next.ddev.site
• Back end:https://api.starter-next.ddev.com

If you would like to use different URLs, you must make a few changes in.ddev/config.yaml:

• Update thename key (this influences thestarter-project segment of the base URL);
• Change the back-end hostname under theadditional_hostnames key;
• Change theVIRTUAL_HOST domains underweb_environment;

Then, a change is required for each of the nginx configuration files:

• Change theserver_name directive in.ddev/nginx_full/api-site.conf to match the back-end url;
• Change theserver_name directive in.ddev/nginx_full/next-site.conf to match the front-end url;

Next.js also needs to be told what front-end URLs should look like:

• UpdateBASE_URL infrontend/.env;

Finally, Craft may need to generate absolute URLs to the control panel in some scenarios:

• UpdateCRAFT_BASE_CP_URL inbackend/.env;

Your production configuration will probably look different—as long as Next.js knows where the GraphQL endpoint lives (CRAFT_URL infrontend/.env) and both Craft and Next.js know how to generate public URLs (PRIMARY_SITE_URL inbackend/.env andBASE_URL infrontend/.env, respectively) these URLs don’t need to be related in any specific way!

Thepath Next.js uses to fetch data via GraphQL must be kept in sync betweenbackend/config/routes.php and theapiBasePath variable infrontend/src/lib/graphql.js.

Pull requests are welcome. Significant structural or aesthetic changes should be submitted as anissue.