Skip to main content

Templates

Templates are pre-made Strapi configurations designed for specific use cases. They allow bootstrapping a custom Strapi application. A template can configure collection types and single types, components and dynamic zones, and plugins.

🤓 Templates vs. Starters
  • A template is only useful once applied on top of a default Strapi application via the CLI. It is not a configured application and cannot be run on its own since it lacks many files (e.g. database configurations, package.json, etc.).
  • A starter is a pre-made frontend application that consumes a Strapi API.

Using a template​

To create a new Strapi project based on a template, run the following command:

yarn create strapi-app my-project --template <template-package>

npm is used to install template packages, so <template-package> can match any format supported by npm install. This includes npm packages, scoped packages, packages with a precise version or tag, and local directories for development.

tip

For convenience, official Strapi templates also have a shorthand, making it possible to omit the @strapi/template- prefix from the template npm package name:

# use the full template name
yarn create strapi-app my-project --template @strapi/template-blog

# use the shorthand
yarn create strapi-app my-project --template blog

The --template option can be used in combination with all other create-strapi-app options (e.g. --quickstart or --no-run).

Creating a template​

Templates are generated from a customized Strapi application and published to the npm package registry. Before creating a template make sure you have a Strapi application that matches your use case and that you have read the template requirements.

Requirements​

Keep the following requirements in mind when creating a template:

  • Templates should not deal with environment-specific configurations (e.g. databases or upload and email providers). This keeps templates maintainable and avoids conflicts with other CLI options (e.g. --quickstart).

  • Templates must follow a specific file structure, containing the following at the repository's root:

This structure can be created manually or automatically generated with the strapi templates:generate command:

yarn strapi templates:generate <path>

The repository root can contain any other files or directories desired, but must include the template directory, package.json file, and template.json file at a minimum.

template directory​

The template directory is used to extend the file contents of a Strapi project and should only include the files that will overwrite the default Strapi application.

Only the following contents are allowed inside the template directory:

  • README.md: the readme of an application made with this template
  • .env.example to specify required environment variables
  • src/
  • data/ to store the data imported by a seed script
  • public/ to serve files
  • scripts/ for custom scripts
caution

If any unexpected file or directory is found, the installation will crash.

template.json file​

The template.json is used to extend the Strapi application's default package.json. All properties overwriting the default package.json should be included in a root package property:

./template.json

{
  "package": {
    "dependencies": {
      "@strapi/plugin-graphql": "^4.0.0"
    },
    "scripts": {
      "custom": "node ./scripts/custom.js"
    }
  }
}

Packaging and publishing​

With the above requirements in mind, follow these steps to create and publish a template:

  1. Create a standard Strapi application with create-strapi-app, using the --quickstart option.
  2. Customize your application to match the needs of your use case.
  3. Generate your template using the CLI by running strapi templates:generate <path>
  4. Navigate to this path to see your generated template.
  5. If you have modified your application's package.json, include these changes (and only these changes) in template.json in a package property. If not, leave it as an empty object.
  6. Enter npm publish to make your template available on the npm package registry.