From 80d1cc066682cfac2210ab5f07099056d8f9d514 Mon Sep 17 00:00:00 2001 From: Jason Varga Date: Thu, 14 Nov 2024 15:04:57 -0500 Subject: [PATCH 1/5] wip --- .../docs/creating-a-starter-kit.md | 110 ++++++++++++++---- .../docs/updating-a-starter-kit.md | 37 ++++++ content/trees/collections/docs.yaml | 2 + content/trees/navigation/docs.yaml | 3 + 4 files changed, 129 insertions(+), 23 deletions(-) create mode 100644 content/collections/docs/updating-a-starter-kit.md diff --git a/content/collections/docs/creating-a-starter-kit.md b/content/collections/docs/creating-a-starter-kit.md index 65596ddce..425ef3226 100644 --- a/content/collections/docs/creating-a-starter-kit.md +++ b/content/collections/docs/creating-a-starter-kit.md @@ -17,17 +17,21 @@ The **Export** command will export all the files and directories you've created 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 ``` @@ -37,8 +41,50 @@ For example, maybe you are creating a pre-built, theme-style Starter Kit, the hi 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 add 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 `composer.json` files. + +``` 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 Kit updatable (more on that below), 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] +} +``` + +## Exporting When ready to export your Starter Kit, run the following command: @@ -46,7 +92,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. +::: + +## Export paths + +Any files that you modify on your site that you intend to be installed into a Statamic project should be marked for export 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,20 +123,6 @@ 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. - -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 @@ -333,6 +373,30 @@ statamic new kung-fury-dev the-hoff/kung-fury-theme --with-config This will install your Starter Kit into a brand new Statamic project, along with your `starter-kit.yaml` config file for future exports. +## Making Starter Kits Updatable + +As their name implies, Starter Kits were originally intended to be a way to "start" a site. Once installed, the user is on their own and can customize as they see fit. + +The Kit would get installed via Composer, files would get copied to their respective locations, and then the Kit gets removed. + +However, you may choose to construct your Kit in a way that it can be updated by the end user. To do that, you should instruct Statamic to leave the Kit required as a Composer dependency by adding `updatable: true` in your `starter-kit.yaml` file: + +```yaml +updatable: true #[tl! ++] +export_paths: ... +``` + +Now that the Kit package stays around after installation, it can be updated like any other Composer package: + +```shell +composer update +``` + +This means that you could do things like: +- Add a service provider to wire up Laravel or Statamic behavior. +- Make the service provider extend AddonServiceProvider to make your Starter Kit _also_ an addon to get behavior for free like autoload tags, modifiers, etc. +- Rather than exporting views, CSS, JS, PHP classes, etc. into the project, you can keep them in the package itself. + ## Addons vs. Starter Kits @@ -349,11 +413,11 @@ Both addons and Starter Kits can be used to extend the Statamic experience, but An example use case is a custom fieldtype maintained by a third party vendor. Though you would install and use the addon within your app, you would still rely on the vendor to maintain and update the addon over time. ::: -### Starters Kits +### Starter Kits -- Starter kits are installed via `php please starter-kit:install` +- Starter kits are installed via `statamic new` or `php please starter-kit:install` - Starter kits install pre-configured files and settings into your site -- Starter kits do not live as updatable packages within your apps +- Starter kits do not live as updatable packages within your apps (by default) - Starter kit licenses are not tied to a specific site, and expire after a successful install :::tip diff --git a/content/collections/docs/updating-a-starter-kit.md b/content/collections/docs/updating-a-starter-kit.md new file mode 100644 index 000000000..f99afef6f --- /dev/null +++ b/content/collections/docs/updating-a-starter-kit.md @@ -0,0 +1,37 @@ +--- +id: 512cbb65-0091-47e2-a3b6-c42aae64349e +blueprint: page +title: 'Updating a Starter Kit' +intro: | + Starter Kits aren't all designed to be updatable, but when they are you'll need to know how. +template: page +nav_title: Updating +--- + +## Not all starter kits are updatable + +As their name implies, starter kits were originally intended to be a way to "start" a site. Once installed, you're on your own and can customize as you see fit. + +However, some kits _are_ built in a way that they can be updated. Updatable kits will be noted on the Statamic Marketplace. + +For example, the [Podcaster](https://statamic.com/starter-kits/statamic/podcaster) kit is designed in an opinionated way, with settings for you to tweak brand colors. If a CSS or JavaScript bug is encountered one day, the +developer of the kit can fix it and you can simply pull down the update into your site. + +## Performing updates + +When initially installing an updatable starter kit, it will be left as a dependency in your `composer.json` file. + +To update, you will need to update via Composer: + +```shell +composer update +``` + +(Or `composer update vendor/starter-kit-name` to avoid updating everything else.) + +Additionally, you may need to run additional commands to re-compile or publish assets. These should be explained in the Starter Kit's documentation, but would typically be something like this: + +```shell +php artisan vendor:publish --tag=starter-kit-name +npm run dev +``` diff --git a/content/trees/collections/docs.yaml b/content/trees/collections/docs.yaml index bcd971f25..2fcf38319 100644 --- a/content/trees/collections/docs.yaml +++ b/content/trees/collections/docs.yaml @@ -152,6 +152,8 @@ tree: entry: 9c703f43-30de-4f65-98bb-2b89f80012b7 - entry: c51a5de8-4b02-4240-8195-3ff7987c43cf + - + entry: 512cbb65-0091-47e2-a3b6-c42aae64349e - entry: a66f3e5f-5a60-44c4-8c1d-a9d9692366c0 - diff --git a/content/trees/navigation/docs.yaml b/content/trees/navigation/docs.yaml index 2bcbac2ad..89f67a243 100644 --- a/content/trees/navigation/docs.yaml +++ b/content/trees/navigation/docs.yaml @@ -237,6 +237,9 @@ tree: - id: a6efd593-b837-46c8-8a36-7bd4b509cf0c entry: c51a5de8-4b02-4240-8195-3ff7987c43cf + - + id: c00f0b6d-2cae-4707-af04-a62cf78a2ca8 + entry: 512cbb65-0091-47e2-a3b6-c42aae64349e - id: f36f50e5-1935-4203-8c02-4d71965a4d2c entry: 9c703f43-30de-4f65-98bb-2b89f80012b7 From a172afce675a78d667d02959ce02335885b59900 Mon Sep 17 00:00:00 2001 From: Jesse Leite Date: Thu, 14 Nov 2024 16:17:48 -0500 Subject: [PATCH 2/5] Small tweaks. --- content/collections/docs/creating-a-starter-kit.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/content/collections/docs/creating-a-starter-kit.md b/content/collections/docs/creating-a-starter-kit.md index 425ef3226..e4065cbd9 100644 --- a/content/collections/docs/creating-a-starter-kit.md +++ b/content/collections/docs/creating-a-starter-kit.md @@ -47,13 +47,13 @@ Run the `init` command to generate the appropriate files. php please starter-kit:init ``` -This command will add a `package` directory, which represents the eventual starter kit repository's root directory. +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 `composer.json` files. +At a minimum, your `package` directory needs a `starter-kit.yaml` and a `composer.json` file. ``` files theme:serendipity-light app/ @@ -67,7 +67,7 @@ resources/ composer.json ``` -If you plan to make your Kit updatable (more on that below), you should require this as a path repository. +If you plan to [make your Starter Kit updatable](#making-starter-kits-updatable), you should require this as a path repository. ```json { @@ -84,6 +84,10 @@ If you plan to make your Kit updatable (more on that below), you should require } ``` +:::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: @@ -157,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 ``` From 7284c2218aa29ffea3287ca437bf439d0b201c19 Mon Sep 17 00:00:00 2001 From: Jesse Leite Date: Thu, 14 Nov 2024 16:20:24 -0500 Subject: [PATCH 3/5] Title case OCD. --- .../docs/creating-a-starter-kit.md | 40 +++++++++---------- .../docs/installing-a-starter-kit.md | 2 +- .../docs/updating-a-starter-kit.md | 11 +++-- 3 files changed, 26 insertions(+), 27 deletions(-) diff --git a/content/collections/docs/creating-a-starter-kit.md b/content/collections/docs/creating-a-starter-kit.md index e4065cbd9..51c46b920 100644 --- a/content/collections/docs/creating-a-starter-kit.md +++ b/content/collections/docs/creating-a-starter-kit.md @@ -8,16 +8,16 @@ 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: +2. Initialize it as a Starter Kit: ```shell php please starter-kit:init ``` @@ -39,7 +39,7 @@ 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. @@ -96,7 +96,7 @@ When ready to export your Starter Kit, run the following command: php please starter-kit:export {export_repo_path} ``` -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. +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. @@ -130,7 +130,7 @@ Once your export paths are configured, re-run the above `starter-kit:export` com ## 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: @@ -139,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. @@ -185,7 +185,7 @@ modules: ```
- Starter kit custom prompt text + Starter Kit custom prompt text
Would you also like fries with that?
@@ -209,7 +209,7 @@ modules: ```
- Starter kit select module + Starter Kit select module
### Customizing Select Modules @@ -237,13 +237,13 @@ modules: ```
- Customizing starter kit select module + Customizing Starter Kit select module
🐮🐮🐮
### Skipping Confirmation -Or maybe you wish to skip the user prompt and always install a given module, using modules to better organize larger starter kit configs. To do this, simply set `prompt` to false. +Or maybe you wish to skip the user prompt and always install a given module, using modules to better organize larger Starter Kit configs. To do this, simply set `prompt` to false. ```yaml modules: @@ -273,9 +273,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 Date: Thu, 14 Nov 2024 16:23:03 -0500 Subject: [PATCH 4/5] =?UTF-8?q?Make=20these=20sub-headings=20under=20`Expo?= =?UTF-8?q?rting`=20section=20=F0=9F=A4=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/collections/docs/creating-a-starter-kit.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/collections/docs/creating-a-starter-kit.md b/content/collections/docs/creating-a-starter-kit.md index 51c46b920..9636ff3b8 100644 --- a/content/collections/docs/creating-a-starter-kit.md +++ b/content/collections/docs/creating-a-starter-kit.md @@ -102,7 +102,7 @@ This will copy and arrange the appropriate files into the given directory that w 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. ::: -## Export paths +### Exporting Paths Any files that you modify on your site that you intend to be installed into a Statamic project should be marked for export in your `starter-kit.yaml` file. @@ -128,7 +128,7 @@ 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. -## Exporting Dependencies +### 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: From e973d22e446409d4e3356878acee32e908aae269 Mon Sep 17 00:00:00 2001 From: Jesse Leite Date: Thu, 14 Nov 2024 16:25:19 -0500 Subject: [PATCH 5/5] Mention `export_paths` in wording. --- content/collections/docs/creating-a-starter-kit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/docs/creating-a-starter-kit.md b/content/collections/docs/creating-a-starter-kit.md index 9636ff3b8..c33c7fad8 100644 --- a/content/collections/docs/creating-a-starter-kit.md +++ b/content/collections/docs/creating-a-starter-kit.md @@ -104,7 +104,7 @@ Think of the exported directory similar to a compiled assets directory when usin ### Exporting Paths -Any files that you modify on your site that you intend to be installed into a Statamic project should be marked for export in your `starter-kit.yaml` file. +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.