statamic / cms

The core Laravel CMS Composer package
https://statamic.com
Other
4.09k stars 534 forks source link

[5.x] Add new `package` folder convention for starter kits #11119

Open jesseleite opened 1 week ago

jesseleite commented 1 week ago

The Problem

When making a kit composer updatable (by setting updatable: true introduced by https://github.com/statamic/cms/pull/11064), you're likely going to want to provide your own package service provider class, PSR-4 namespace, vendor views, etc. that are separate from export_paths (which get installed into the users app, rather than remaining in vendor). Right now there is no way to automatically export those vendor files to your starter kit repo.

The Solution

In this PR, we now expect a package folder in your dev application for all your package's vendor files...

CleanShot 2024-11-14 at 16 41 18

These files will be exported to the root of your shippable repo when running starter-kit:export.

We also export all of your files export_paths to an export folder in your shippable repo to keep things clean and free from filename conflicts.

For example, if this is your dev app...

├─ app
│  └─ file.php
├─ config
├─ resources
├─ etc
│ 
├─ package
│  ├─ src
│  │  └─ Tags
│  │     └─ Foo.php
│  ├─ resources
│  │  ├─ css
│  │  ├─ js
│  │  └─ views
│  │     ├─ default.antlers.html
│  │     └─ layout.antlers.html
│  └─ composer.json
│ 
├─ composer.json
└─ starter-kit.yaml

Then this is what the final export will look like...

├─ export
│  └─ app
│     └─ file.php
├─ src
│  └─ Tags
│     └─ Foo.php
├─ resources
│  ├─ css
│  ├─ js
│  └─ views
│     ├─ default.antlers.html
│     └─ layout.antlers.html
├─ composer.json
└─ starter-kit.yaml

This lets you manage your package's composer.json, etc. from the package folder, and the exporter and installer will intelligently put Everything in Its Right Place, just like Radiohead.

Think of the exported directory similar to a compiled assets directory when using a build tool like Vite. You export/generate files into this directory, and shouldn't touch it manually.

Todo