@devkitlab/create-devkitlab-nextjs 0.1.6 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +64 -29
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,16 +1,18 @@
1
- # create-devkitlab-nextjs
1
+ # @devkitlab/create-devkitlab-nextjs
2
2
 
3
- `create-devkitlab-nextjs` scaffolds a DevkitLab-flavored Next.js starter with TypeScript, Tailwind CSS, and the bundled project template.
3
+ CLI package for scaffolding the DevkitLab Next.js starter.
4
4
 
5
- The `template/` directory in this repository is a Git submodule. The source of truth for the starter lives in that separate template repository, and this package repo publishes whatever template commit is currently pinned.
5
+ This repository is the npm package repo. The actual starter source lives in the separate template repository and is tracked here through the [`template/`](/Users/shahadat/projects/NextJs-Starter/template) Git submodule.
6
6
 
7
- ## Usage
7
+ ## Install and Use
8
+
9
+ Create a new project with:
8
10
 
9
11
  ```bash
10
- npx create-devkitlab-nextjs@latest my-app
12
+ npx @devkitlab/create-devkitlab-nextjs@latest my-app
11
13
  ```
12
14
 
13
- Then:
15
+ Then start the generated app:
14
16
 
15
17
  ```bash
16
18
  cd my-app
@@ -18,34 +20,58 @@ npm install
18
20
  npm run dev
19
21
  ```
20
22
 
21
- ## What It Generates
23
+ If you prefer, you can use `pnpm` or `yarn` instead of `npm`.
24
+
25
+ ## What the CLI Generates
22
26
 
23
- - Next.js + App Router
27
+ - Next.js App Router starter
24
28
  - TypeScript
25
29
  - Tailwind CSS
26
30
  - Sanity starter wiring
27
- - ESLint, Prettier, Husky, and lint-staged
31
+ - ESLint and Prettier
32
+ - Husky and lint-staged
33
+
34
+ ## Repository Layout
35
+
36
+ - [`bin/`](/Users/shahadat/projects/NextJs-Starter/bin) contains the executable used by `npx`
37
+ - [`template/`](/Users/shahadat/projects/NextJs-Starter/template) is the starter template Git submodule
38
+ - [`.github/workflows/publish.yml`](/Users/shahadat/projects/NextJs-Starter/.github/workflows/publish.yml) publishes the package from GitHub Actions
39
+
40
+ ## How Publishing Works
41
+
42
+ This package publishes through GitHub Actions using npm Trusted Publishing.
43
+
44
+ - Package repo: this repository
45
+ - Template repo: the repository pointed to by [`.gitmodules`](/Users/shahadat/projects/NextJs-Starter/.gitmodules)
46
+ - Package name: `@devkitlab/create-devkitlab-nextjs`
47
+ - Workflow: [`publish.yml`](/Users/shahadat/projects/NextJs-Starter/.github/workflows/publish.yml)
28
48
 
29
- ## Publish
49
+ The workflow can run in three ways:
30
50
 
31
- GitHub can publish this package to npm for you.
51
+ 1. Push changes to `main` that affect [`package.json`](/Users/shahadat/projects/NextJs-Starter/package.json), [`.gitmodules`](/Users/shahadat/projects/NextJs-Starter/.gitmodules), or [`template/`](/Users/shahadat/projects/NextJs-Starter/template).
52
+ 2. Trigger `repository_dispatch` from the template repo after template updates.
53
+ 3. Run it manually with GitHub Actions `workflow_dispatch`.
32
54
 
33
- ### Repository setup
55
+ During a template-triggered run, the workflow:
34
56
 
35
- - Keep this repo as the npm package repo.
36
- - Keep the starter app in a separate template repo.
37
- - Track that template repo in this package repo via the [`template/`](/Users/shahadat/projects/NextJs-Starter/template) Git submodule.
57
+ 1. Updates the `template` submodule to the latest remote commit.
58
+ 2. Bumps the package version with a patch release.
59
+ 3. Commits the new submodule pointer back to `main`.
60
+ 4. Publishes the package to npm if that version is not already published.
38
61
 
39
- ### One-time setup in the package repo
62
+ ## One-Time Setup
40
63
 
41
- 1. Create an npm access token at `npmjs.com`.
42
- 2. Add it to your GitHub repository secrets as `NPM_TOKEN`.
43
- 3. If the template repo is private, add a secret named `TEMPLATE_REPO_TOKEN` with read access to that repo.
44
- 4. Make sure the package name in `package.json` is available on npm.
64
+ ### Package Repo
45
65
 
46
- ### One-time setup in the template repo
66
+ 1. Create the npm package `@devkitlab/create-devkitlab-nextjs` if it does not exist yet by letting the first successful publish create it.
67
+ 2. In npm package settings, add a Trusted Publisher for this GitHub repository and this workflow file: `publish.yml`.
68
+ 3. If the template repository is private, add a GitHub Actions secret named `TEMPLATE_REPO_TOKEN` with read access to the template repo.
47
69
 
48
- When the template repo is pushed, it should send a `repository_dispatch` event to this package repo. A minimal workflow in the template repo looks like this:
70
+ ### Template Repo
71
+
72
+ Configure the template repo to notify this package repo when the template changes.
73
+
74
+ Example workflow for the template repo:
49
75
 
50
76
  ```yaml
51
77
  name: Notify package repo
@@ -67,16 +93,25 @@ jobs:
67
93
  -X POST \
68
94
  -H "Accept: application/vnd.github+json" \
69
95
  -H "Authorization: Bearer ${GH_TOKEN}" \
70
- https://api.github.com/repos/shahadat-robin/nextjs-page-rendering/dispatches \
96
+ https://api.github.com/repos/shahadat-robin/devkitlab-nextjs/dispatches \
71
97
  -d '{"event_type":"template_updated","client_payload":{"ref":"main"}}'
72
98
  ```
73
99
 
74
- The `PACKAGE_REPO_DISPATCH_TOKEN` secret should be a GitHub token that can dispatch workflows to the package repo.
100
+ `PACKAGE_REPO_DISPATCH_TOKEN` must have permission to dispatch workflows to the package repo.
101
+
102
+ ## Updating the Template Manually
75
103
 
76
- ### Release flow
104
+ If you want to update the template submodule locally:
105
+
106
+ ```bash
107
+ git submodule update --init --remote template
108
+ git add template .gitmodules
109
+ git commit -m "chore: update template submodule"
110
+ git push origin main
111
+ ```
77
112
 
78
- 1. Push changes to the template repo.
79
- 2. The template repo dispatches `template_updated` to the package repo.
80
- 3. The package repo workflow updates the [`template/`](/Users/shahadat/projects/NextJs-Starter/template) submodule to the latest remote commit, bumps the npm package version, commits the new submodule pointer, and publishes to npm.
113
+ ## Troubleshooting
81
114
 
82
- You can also run the same package workflow manually from GitHub Actions with `workflow_dispatch`, or continue publishing from a GitHub Release if you prefer.
115
+ - If GitHub Actions does not start after a push, confirm the commit changed [`package.json`](/Users/shahadat/projects/NextJs-Starter/package.json), [`.gitmodules`](/Users/shahadat/projects/NextJs-Starter/.gitmodules), or something inside [`template/`](/Users/shahadat/projects/NextJs-Starter/template).
116
+ - If npm publish fails with auth errors, verify the npm Trusted Publisher configuration exactly matches this repository and the workflow filename `publish.yml`.
117
+ - If the template repo is private and submodule checkout fails, verify `TEMPLATE_REPO_TOKEN` is present in GitHub Actions secrets.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@devkitlab/create-devkitlab-nextjs",
3
- "version": "0.1.6",
3
+ "version": "0.1.7",
4
4
  "description": "Create a DevkitLab Next.js starter app with TypeScript and Tailwind CSS.",
5
5
  "type": "module",
6
6
  "bin": {