diff --git a/content/collections/docs/creating-a-starter-kit.md b/content/collections/docs/creating-a-starter-kit.md index 9145fb570..95be2851a 100644 --- a/content/collections/docs/creating-a-starter-kit.md +++ b/content/collections/docs/creating-a-starter-kit.md @@ -8,26 +8,30 @@ nav_title: Creating --- ## Overview -Starter kit development happens within a real instance of Statamic, just like developing any other Statamic site using your normal, preferred workflows. +Starter Kit development happens within a real instance of Statamic, just like developing any other Statamic site using your normal, preferred workflows. -A released Starter Kit package contains **only** the files relevant to the kit itself, and not a full Statamic/Laravel instance. Our Import/Export tools will allow you to maintain **only those relevant files**, without having to worry about maintaining the Statamic and underlying Laravel instances as they get updated over time. +A released Starter Kit package contains **only** the files relevant to the Kit itself, and not a full Statamic/Laravel instance. Our Import/Export tools will allow you to maintain **only those relevant files**, without having to worry about maintaining the Statamic and underlying Laravel instances as they get updated over time. The **Export** command will export all the files and directories you've created or configured to a new location. It's this directory that becomes the package, and is the thing you should version control, not the sandbox instance. For example, maybe you are creating a pre-built, theme-style Starter Kit, the high-level workflow might look like this: 1. Create a new Statamic project. +2. Initialize it as a Starter Kit: + ```shell + php please starter-kit:init + ``` -2. Develop the theme as you normally would. +3. Develop the theme as you normally would. -3. Export the theme to a separate repo for redistribution. +4. Export the theme to a separate repo for redistribution. ``` shell php please starter-kit:export ../kung-fury-theme ``` -4. Publish to [Github](https://github.com/), [Gitlab](https://gitlab.com/), or [Bitbucket](https://bitbucket.org/). +5. Publish to [Github](https://github.com/), [Gitlab](https://gitlab.com/), or [Bitbucket](https://bitbucket.org/). -5. Install into new Statamic projects. +6. Install into new Statamic projects. ``` shell php please starter-kit:install the-hoff/kung-fury-theme ``` @@ -35,10 +39,56 @@ For example, maybe you are creating a pre-built, theme-style Starter Kit, the hi ## Creating the Starter Kit Project -The first step is to [create a new Statamic project](/installing#creating-a-new-statamic-project). This is essentially a throwaway sandbox that you will use to develop and test your starter kit. +The first step is to [create a new Statamic project](/installing#creating-a-new-statamic-project). This is essentially a throwaway sandbox that you will use to develop and test your Starter Kit. +Run the `init` command to generate the appropriate files. -## Exporting Files +```shell +php please starter-kit:init +``` + +This command will create and wire up a `package` directory, which represents the eventual Starter Kit repository's root directory. + +## The Starter Kit Package + +Starter Kits are installed via Composer. You can control the package's contents via the `package` directory, which will be the exported repository's root directory. + +At a minimum, your `package` directory needs a `starter-kit.yaml` and a `composer.json` file. + +``` files theme:serendipity-light +app/ +content/ +config/ +package/ #[tl! ++] + composer.json #[tl! ++] + starter-kit.yaml #[tl! ++] +public/ +resources/ +composer.json +``` + +If you plan to [make your Starter Kit updatable](#making-starter-kits-updatable), you should require this as a path repository. + +```json +{ + "name": "statamic/statamic", + "require": [ + "the-hoff/kung-fury-theme": "dev-master" // [tl! ++] + ], + "repositories": [ // [tl! ++:start] + { + "type": "path", + "url": "package" + } + ] // [tl! ++:end] +} +``` + +:::tip +Ths `package` folder can be automatically scaffolded and wired up in your composer `repositories` by [running the init command](#creating-the-starter-kit-project) to create your Starter Kit project. +::: + +## Exporting When ready to export your Starter Kit, run the following command: @@ -46,7 +96,15 @@ When ready to export your Starter Kit, run the following command: php please starter-kit:export {export_repo_path} ``` -If you are exporting for the first time, a new `starter-kit.yaml` config file will be created in your app's root, and you will be instructed to configure which `export_paths` you would like to export. +This will copy and arrange the appropriate files into the given directory that will be used as a distributable on GitHub, GitLab, Bitbucket, Composer, etc. + +:::tip +Think of the exported directory similar to a compiled assets directory when using a build tool like Vite. You generate files into this directory and shouldn't touch it manually. +::: + +### Exporting Paths + +Any files that you modify on your site that you intend to be installed into a Statamic project should be marked as `export_paths` in your `starter-kit.yaml` file. For example, the following config would tell Statamic to export sample content, along with related assets, config, blueprints, css, views, and front-end build config out for distribution on the Statamic Marketplace. @@ -69,24 +127,10 @@ Anything not configured in your `starter-kit.yaml` **will not be exported**. Thi Once your export paths are configured, re-run the above `starter-kit:export` command. Your files should now be available at your new export repo path. -### Avoiding Path Conflicts -If you have a filename conflict between your sandbox and your starter kit repo, you can use `export_as` to customize its export path. +### Exporting Dependencies -For example, you may wish to export a `README.md` for installation into new sites that is separate from the `README.md` in your starter kit repo. - -``` yaml -export_as: - file-in-sandbox.md: file-in-exported-repo.md - README.md: README-for-new-site.md -``` - -This will instruct `starter-kit:export` to rename each of those paths on export, and in reverse on `starter-kit:install` to match where you had them in your sandbox app. - - -## Exporting Dependencies - -If you wish to bundle any of your installed Composer dependencies with your starter-kit, just `composer require` them in your sandbox project as you would into any app, then add them under a `dependencies` array in your `starter-kit.yaml` config file: +If you wish to bundle any of your installed Composer dependencies with your Starter Kit, just `composer require` them in your sandbox project as you would into any app, then add them under a `dependencies` array in your `starter-kit.yaml` config file: ``` yaml dependencies: @@ -95,12 +139,12 @@ dependencies: The exporter will automatically detect the installed versions and whether or not they are installed as dev dependencies, and export accordingly. -When [installing the starter kit](#installing-a-starter-kit), composer will install with the same version constraints as you had installed in your sandbox project during development. +When [installing the Starter Kit](#installing-a-starter-kit), composer will install with the same version constraints as you had installed in your sandbox project during development. ## Optional Modules -You may also present an optional set of starter kit files, nested under `modules` in your `starter-kit.yaml` config file. +You may also present an optional set of Starter Kit files, nested under `modules` in your `starter-kit.yaml` config file. For example, here we'll configure an opt-in `seo` module. @@ -117,15 +161,13 @@ This presents a choice to the user, to confirm whether or not to install this mo The user can confirm whether or not to install the `seo` module -These modules are compatible with the same config options that you use at the top level of your config file (ie. `export_paths`, `export_as`, `dependencies`, etc.). +These modules are compatible with the same config options that you use at the top level of your config file (ie. `export_paths`, `dependencies`, etc.). ```yaml modules: seo: export_paths: - resources/css/seo.css - export_as: - README.md: README-for-seo.md dependencies: - statamic/seo-pro ``` @@ -143,7 +185,7 @@ modules: ```
- Starter kit custom prompt text + Starter Kit custom prompt text
Would you also like fries with that?
@@ -189,7 +231,7 @@ modules: ```
- Starter kit select module + Starter Kit select module
### Customizing Select Module Prompt Text @@ -217,7 +259,7 @@ modules: ```
- Customizing starter kit select module + Customizing Starter Kit select module
🐮🐮🐮
@@ -272,9 +314,9 @@ In this example, the second `sitemap` module prompt will only be presented to th ## Post-Install Hooks -You may run additional logic after the starter kit is installed. For example, maybe you want to output some information. +You may run additional logic after the Starter Kit is installed. For example, maybe you want to output some information. -To do so, you can create a `StarterKitPostInstall.php` file in the root of your starter kit. It should be a simple non-namespaced class with a `handle` method. You will be provided with an instance of the command so you can output lines, get input, and so on. +To do so, you can create a `StarterKitPostInstall.php` file in the root of your Starter Kit. It should be a simple non-namespaced class with a `handle` method. You will be provided with an instance of the command so you can output lines, get input, and so on. ```php