mirror of
https://github.com/strapi/strapi.git
synced 2025-08-07 08:16:35 +00:00
100 lines
3.9 KiB
Markdown
100 lines
3.9 KiB
Markdown
# Templates
|
|
|
|
A template is a pre-made Strapi configuration designed for a specific use case. It allows you to quickly bootstrap a custom Strapi app.
|
|
|
|
Here are some things a template may configure for you:
|
|
|
|
- Collection types and single types
|
|
- Components and dynamic zones
|
|
- Plugins to install, or custom plugins
|
|
|
|
::: warning
|
|
Templates and starters are not the same thing:
|
|
|
|
- A _template_ is a pre-made Strapi configuration. Note that it's only a configuration, not a configured application. That's because it cannot be run on its own, since it lacks many files, like database configs or the `package.json`. A template is only useful once applied on top of a default Strapi app via the CLI.
|
|
- A _starter_ is a pre-made frontend application that consumes a Strapi API
|
|
|
|
:::
|
|
|
|
## Using a template
|
|
|
|
You can use a template when creating a project with `create-strapi-app`.
|
|
|
|
:::: tabs
|
|
|
|
::: tab yarn
|
|
|
|
```bash
|
|
yarn create strapi-app my-project --template <template-github-url>
|
|
```
|
|
|
|
:::
|
|
|
|
::: tab npx
|
|
|
|
```bash
|
|
npx create-strapi-app my-project --template <template-github-url>
|
|
```
|
|
|
|
:::
|
|
|
|
::::
|
|
|
|
You can use the `--template` option in combination with all other `create-strapi-app` options, like `--quickstart` or `--no-run`.
|
|
|
|
## Creating a template
|
|
|
|
To create a Strapi template, you need to publish a public GitHub repository that follows some rules.
|
|
|
|
First, a template's only concern should be to adapt Strapi to a use case. It should not deal with environment-specific configs, like databases, or upload and email providers. This is to make sure that templates stay maintainable, and to avoid conflicts with other CLI options like `--quickstart`.
|
|
|
|
Second, a template must follow the following file structure.
|
|
|
|
### File structure
|
|
|
|
You can add as many files as you want to the root of your template repository. But it must at least have a `template.json` file and a `template` directory.
|
|
|
|
The `template.json` is used to extend the Strapi app's default `package.json`. You can put all the properties that should overwrite the default `package.json` in a root `package` property. For example, a `template.json` might look like this:
|
|
|
|
```json
|
|
{
|
|
"package": {
|
|
"dependencies": {
|
|
"strapi-plugin-graphql": "latest"
|
|
},
|
|
"scripts": {
|
|
"custom": "node ./scripts/custom.js"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The `template` directory is where you can extend the file contents of a Strapi project. All the children are optional, you should only include the files that will overwrite the default Strapi app.
|
|
|
|
Only the following contents are allowed inside the `template` directory:
|
|
|
|
- `README.md`: the readme of an app made with this template
|
|
- `.env.example`: to specify required environment variables
|
|
- `api/`: for collections and single types
|
|
- `components/` for components
|
|
- `config/` can only include the `functions` directory (things like `bootstrap.js` or `404.js`), because other config files are environment-specific.
|
|
- `data/` to store the data imported by a seed script
|
|
- `plugins/` for custom Strapi plugins
|
|
- `public/` to serve files
|
|
- `scripts/` for custom scripts
|
|
|
|
If any unexpected file or directory is found, the installation will crash.
|
|
|
|
### Step by step
|
|
|
|
After reading the above rules, follow these steps to create your template:
|
|
|
|
1. Create a standard Strapi app with `create-strapi-app`, using the `--quickstart` option.
|
|
2. Customize your app to match the needs of your use case.
|
|
3. Outside of Strapi, create a new directory for your template.
|
|
4. Create a `template.json` file in your template directory.
|
|
5. If you have modified your app's `package.json`, include these changes (and _only_ these changes) in `template.json` in a `package` property. Otherwise, leave it as an empty object.
|
|
6. Create a `/template` subdirectory.
|
|
7. Think of all the files you have modified in your app, and copy them to the `/template` directory
|
|
8. Publish the root template project on GitHub. Make sure that the repository is public, and that the code is on the `master` branch.
|