Starter Kit Improvements

[jesseleite]

Starter Kits

• Goals
• Concept
• Development Workflow
• TLDR

Goals

1. Improve Marketability

At the moment, there is no way to sell a starter kit on the Statamic Marketplace. Starter kits are like snapshots; They are full Statamic apps, and there is currently no easy way to do a license check on starter-kit installations. Our number one goal is to package starter kits up in a way that could be sellable on the Marketplace.

2. Improve Installability

It is pretty easy to install a starter kit using the Statamic CLI tool, however it would be a great experience if users could also browse and install starter kits from inside the control panel, as is already possible with addons.

3. Improve Maintainability

As Laravel and Statamic updates are released, starter kits must be updated in the same way you would update a regular site. Even if there are no breaking changes, it can be tedious merging configs and updating file structure that is fundamentally unrelated to your actual starter kit. Ideally, we want starter kits to be as easy to maintain as addons. If there are no breaking changes, you should be able to update the version constraint in your composer.json and push a release.

4. Reduce Complexity

Due to the complexity of the current starter kit file structure and development process, we aren't seeing many designers making simple themes for Statamic. It would be nice to get to a place where designers felt more comfortable creating themes, and we feel like the Statamic Marketplace could give designers incentive for more exposure.

Concept

Rather than starter kits being a whole snapshot of a Statamic app, the starter kit would now only contain code unique to the starter kit.

starter-kit/
├── config/             // Configs that are specific to starter kit
├── content/            // Sample content specific to starter kit
├── resources/          // Resources (css, js, views, etc.) specific to starter kit
├── composer.json
├── package.json
├── README.md
├── starter-kit.yaml
├── tailwind.config.js
└── webpack.mix.js

Development Workflow

To develop a starter kit, spin up a fresh instance of a statamic app using statamic/statamic. All of your starter kit development will be done within a real sandbox app, as if you were developing a regular Statamic site using your normal preferred workflows.

Exporting a Starter Kit

When ready to publish your Starter Kit, run php please starter-kit:export ../my-starter-kit. If you are running 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 paths you would like to export, and where you would like to export to. The starter-kit.yaml file will contain common paths, commented out as an example for you.

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. Anything not configured in your starter-kit.yaml will not be exported; This way you don't have to maintain any config and/or bootstrapping that is unrelated to your starter kit.

export_paths:
  - content
  - config/filesystems.php
  - config/statamic/assets.yphp
  - public/assets
  - resources/blueprints
  - resources/css
  - resources/views
  - package.json
  - tailwind.config.js
  - webpack.mix.js

If you are intentionally installing any composer dependencies for the end user, you can instruct the exporter to copy those dependencies from the starter kit's composer.json to the user's composer.json file by defining a dependencies array:

dependencies:
  - statamic/ssg

Publishing a Starter Kit

You will notice that a sample composer.json file was exported into your starter kit. You can modify this to suit, push to Github, Packagist, and distribute on the Statamic Marketplace as you would any other addon.

Installing a Starter Kit

To manually install a starter kit, you would run:

php please starter-kit:install your/starter-kit

If you want to bypass composer constraints, you could run with a --force flag to fetch as a ZIP file instead of requiring via composer.

Note: As mentioned in our goals above, we would also allow the user to install starter kits from within the control panel, as well as via the Statamic CLI installer.

If it is a paid starter kit, Statamic would now perform a license check before allowing the user to proceed. If a purchase is required, we would guide the user through purchasing a license before allowing the installer to proceed.

The user will also be asked if they would like to clear existing site content before importing, but will also be given the ability to opt-out in case they wish to install a starter kit along side of existing content.

The importer would then intelligently merge everything from the starter kit into the user's app (ignoring composer.json, starter-kit.yaml, etc), removing any unessessary dependencies after a successful install.

Maintaining a Starter Kit

To maintain or update your starter kit for future Laravel and/or Statamic versions, it's up to you whether you keep your site up-to-date in the traditional fashion, or with a throw-away-and-import flow like this:

• Run php please starter-kit:install --with-config into a fresh statamic/statamic sandbox app.
• Make your changes.
• Run php please starter-kit:export to export these changes back to your starter kit repo.
• Commit, push, and tag your changes.

Note: The sandbox app used to develop your starter kit is essentially a throwaway site. It's only used for the purpose of development, and it is recommended that you always use an up-to-date version of Statamic. It's also worth noting that your --with-config will copy your existing starter-kit.yaml config so that you don't have to set this up for every export.

TLDR

We believe the above changes to starter kits will make it easier to create, publish, market, and maintain starter kits. Here are the big takeaways:

• Simpler file structure, only including files unique to your starter kit.
• Simple development workflow.
• Intelligent exporter for publishing starter kits.
• Intelligent installer for merging starter kits into users' apps.
• License check for paid starter kits is a one-time check done at the time of installation.
• Once installed, end users should be free to modify anything and everything in their site.

Thoughts? We would love to hear from you!

[vladdu]

Sounds neat!

I am only a user of starter kits and I have a few question marks related mostly to how meaningful it is to install a starter kit in an existing site.

• Can several be installed? If yes, what would that mean?
• Can they be uninstalled?
• How do I customize a starter kit so that it can be updated and my changes are still there (possibly with warnings about things that need to be checked)?

[jesseleite]

Can several be installed? If yes, what would that mean?

Technically yes. A starter kit is just a set of files that gets installed/merged into your site. Maybe one starter kit would add a products collection (and any related blueprints, etc), and maybe another starter kit is a front end theme (with views, css, js, and a webpack build file). There may be overlap between some starter kits, but it's up to you what you choose to install.

Can they be uninstalled?

Absolutely. The installer would remove the starter kit dependency after a successful install. Since an install is essentially merged files into your app, there's no need for it to stick around.

How do I customize a starter kit so that it can be updated and my changes are still there (possibly with warnings about things that need to be checked)?

I think the above answers that. Once installed, you are just editing your own site files, as you would without a starter kit. The difference between starter kits and addons is, starter kits just get you started at the time of install, whereas addons stick around as dependencies.

Hope it helps @vladdu!

[jackmcdade]

The biggest benefit to being able to install a starter kit in an existing site is for "One Click Install" scenarios. You could, conceivably, create a Digital Ocean account, one click spin up a new Statamic site, log in, install a Starter Kit, and start running your new site without ever needing a local dev environment.

[jasonvarga]

Can several be installed?

Again, technically yes, but I don't think this will ever really be something that would be recommended or make sense to do.

Multiple starter kit composer packages could be installed, but you wouldn't be able to switch between them (like a "theme switcher").

IMO you wouldn't change starter kits once you've finished "starting" your site.

Can they be uninstalled

The starter kit packages themselves would be uninstallable, but whatever it applied to your app would stick around.

[vladdu]

Thanks! I suppose I had in mind things like Peak, that both cover a lot of functionality, and are very opinionated. It would be difficult to mix it with other kits that touch the same areas.

If something is available in the CP in production, then it kind of suggests it can be used at any time. It's similar to updating Statamic: I never got to be able to do it from the CP for v2, but it's easy to press the button and make a mess.

Sometimes it's better to restrict when and where things can be started from, IMHO.

[austriker27]

👀 Watching this closely because I think it would really bring a lot of value to the Statamic ecosystem! I think a blocker to people trying Statamic has been lack of starters - they want to install one and kick the tires like is possible with WordPress (and they didn't love the ones that Jack made). I'm hoping this part of the ecosystem can grow and I personally would love to create some starters once this is hammered out.

Sorry I know thats less of a feedback comment and more of a "I'm super excited and can't wait - lets goooooooooo" comment.

[jesseleite]

I suppose I had in mind things like Peak, that both cover a lot of functionality, and are very opinionated. It would be difficult to mix it with other kits that touch the same areas.

Totally @vladdu. Peak is very cool, and like you said (intentionally) very opinionated. With these changes though, starter kits can be as large & opinionated, or as small & modular, as people want them to be.

[aerni]

How would you deal with importing custom logic that is usually in the app folder? Just define that folder as a path as well? And what about routes? An addon can register routes. Would a starter kit just override the web.php file?

[jacksleight]

This sounds great. First question that crossed my mind is would it be possible have local/private starter kits? I already have a client project where we have a base site that gets duplicated for different projects. The design and features are very specific to the client so it wouldn’t have much value to anyone else on the marketplace, but the starter kit system sounds like the perfect way to manage these and get new sites up and running.

[jesseleite]

How would you deal with importing custom logic that is usually in the app folder? Just define that folder as a path as well? And what about routes? An addon can register routes. Would a starter kit just override the web.php file?

@aerni Yes, you could just add app/Whatever/File.php or even routes/web.php to your starter kit. For the initial release, whole files would be merged and/or replaced. This wouldn't be all that different from how starter kits currently work (just a static set of files to start with). That said, it's a great question, and we may eventually provide a way to append individual routes, set specific config settings, etc. without overwriting whole files.

Would it be possible have local/private starter kits?

@jacksleight We're definitely talking about starter kits as private repos, but we're focusing on open source to start.

[jackabox]

I like the idea of this being modular. I have a basic starter kit for Shopify but it only really needs to publish a few assets and blueprints. This will allow for installation on top of other starters for people and remove a bit of friction in the way to do it currently.

Keeping an eye on this :)

[robdekort]

Nice. If I understand correctly you can define any file you want the installer to overwrite during the installation of a starter kit and leave all untouched files out. That sounds very handy. Sometimes it's hard to follow what config files got updated with Statamic updates. Because if they do get updated, it means I have to update them in my starter kit as well. This would greatly simplify that.

I agree with Vlad I'm not sure on the installation via the CP yet. Like you said: it's a starter kit. You install it, expand your site, add content and that's it. A CP panel indeed implies you can go nuts installing, editing, removing, installing something else. On the other hand it would make it easier for a new audience to jump on the Statamic train. Curious to your thoughts on this.

A nice benefit of the current system for me is that I can make changes to the .env.example. I made a few Statamic config settings .env settings. And since a fresh installs copies my .env.example I can ensure users have the correct variables in their environment.

I'm looking forward to this and to designing a few kits myself if time ever permits. Let me know if you need me to test the new functionality.

[jesseleite]

I agree with Vlad I'm not sure on the installation via the CP yet.

@robdekort @vladdu The same arguments against installing starter kits via the CP can be applied to installing Statamic updates and addons via the CP (both of which are already a thing). It's not recommended in production environments, but I see no harm using the CP locally. At the very least, it will give starter kit creators more exposure.

A nice benefit of the current system for me is that I can make changes to the .env.example.

@robdekort There's no reason why you won't be able add .env.example to export_paths in your starter-kit.yaml config. We're not limiting what you can and cannot ship with your starter kit 😊

[robdekort]

@robdekort There's no reason why you won't be able add .env.example to export_paths in your starter-kit.yaml config. We're not limiting what you can and cannot ship with your starter kit 😊

Great, of course. That'll work as well then.

The same arguments against installing starter kits via the CP can be applied to installing Statamic updates and addons via the CP (both of which are already a thing)

I don't think I understand how: "_A starter kit panel in the CP could imply it works like themes do in WP_" applies to the update panel. To me it doesn't make sense to integrate it in the CP when installing a SK is just a one time thing. I'm mostly worried users could get expectations but instead end up disappointed or with a broken site. Since a SK can basically overwrite anything on your website.

[jasonvarga]

You can break your site by installing an addon. The person doing it should know what they're installing.

We can add words explaining what it is.

[jesseleite]

@robdekort If you don't trust end users, you'll have the same ability to deny them permission, just like you can with the CP addon installer and the CP updater...

[robdekort]

For sure. My feedback was not about end users. My worry is the expectation you could set by adding a full fledged starter kit installer to the CP you should actually only use once.

It takes time to develop, maintain and support. The CP installer already raises questions on Discord regularly.

As I said above I really like the ideas. But you asked for feedback so I'm the devils advocate.

[jesseleite]

We very much appreciate the feedback ❤️

I would echo @jasonvarga's point that you can totally break your site by installing an addon through the CP as well. You can even break a site by messing with blueprints, collection configs, etc. through the CP as well. Super users get access to all the dangerous tools 🔪; Everyone else can be limited through permissions ✏️.

[philipboomy]

I agree with @robdekort that a Starter Kit is something you likely do 1 time. Also a starter kit is also not something you can "finish" setting up without touching CLI and/or templates. An addon is not the same at all. Most addons I can install via the CP and set up via the CP. A starter kit not at all. I prefer spending the resources elsewhere.

[edalzell]

How would you deal with importing custom logic that is usually in the app folder? Just define that folder as a path as well? And what about routes? An addon can register routes. Would a starter kit just override the web.php file?

You could also either bundle or build an addon that provided that.

[robdekort]

Idea: it would be nice if you could hook into the the scaffold resources stubs. That way when users of a starter kit generate index and show templates, the starter kit developer can provide the templates wrapped in appropriate styling for that kit.

[jelleroorda]

I have to say I love the ideas for simplifying the creation/maintenance of starter kits. Like the others, I also have some doubts about people thinking that Starter kits are equivalent to themes. I think as long as you "put some words" like Jason said it should be fine. It's called "starter kit" for a reason I suppose. As a developer myself I'd probably always use the terminal, but I can see myself clicking through the starter kits sometimes to see what's available.

The part I really like is that you'd be able to override existing parts of the applications (maybe blueprints/templating), which would mean that you could also potentially use a starter kit as a 'core' to multiple websites. After updating the core, you'd publish the starter kit again in your websites and you'd end up with the latest/greatest.

[jesseleite]

@jelleroorda Appreciate the kind words, and appreciate everyone's feedback.

As a developer myself I'd probably always use the terminal, but I can see myself clicking through the starter kits sometimes to see what's available.

I'm in that boat as well. I understand the pushback about showing them in the CP, but it will only give your paid starter kits more exposure. If you want to deny CP users access to starter kits, you will be able to through roles and permissions.

Like the others, I also have some doubts about people thinking that Starter kits are equivalent to themes. I think as long as you "put some words" like Jason said it should be fine. It's called "starter kit" for a reason I suppose.

Absolutely.

A starter kit can be anything from a theme, to preset config files, to scaffolding a front-end build pipeline, to example content, to an svg icon set, to a set of blueprints for a specific purpose, etc. It can be one of those things, or it can be all of those things.

In the case of a theme, it would generally only make sense to install at the beginning. In the case of an svg icon set, it could be installed anytime, on top of a previously installed theme even. Trying to make this as flexible as possible, so people can get as creative as possible.