Add support for publishing to npm from GitHub (#26)

Author: skirtles-code

.github/workflows/ci.yml

@@ -3,14 +3,13 @@ name: CI
 on:
   push:
     branches:
-      - main
+      - '**'
   pull_request:
     branches:
-      - main
+      - '**'
 
 jobs:
   ci:
-    if: github.repository == 'skirtles-code/create-vue-lib'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -31,4 +30,5 @@ jobs:
       - name: Build
         run: pnpm run build
       - name: Release
+        if: github.repository == 'skirtles-code/create-vue-lib'
         run: pnpx pkg-pr-new publish --bin --commentWithSha --pnpm --packageManager=pnpm './packages/create-vue-lib'

.github/workflows/pages.yml

@@ -22,6 +22,7 @@ concurrency:
 jobs:
   # Single deploy job since we're just deploying
   deploy:
+    if: github.repository == 'skirtles-code/create-vue-lib'
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.github/workflows/publish.yml

@@ -17,6 +17,7 @@ permissions:
 
 jobs:
   publish:
+    if: github.repository == 'skirtles-code/create-vue-lib'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

packages/create-vue-lib/src/index.ts

@@ -86,6 +86,7 @@ type Config = {
   includeVitest: boolean
   includeGithubCi: boolean
   includePkgPrNew: boolean
+  includeNpmPublish: boolean
   includeAtAliases: boolean
   includeTestVariable: boolean
   includeTailwind: boolean
@@ -277,6 +278,7 @@ async function init() {
   const includePlayground = await togglePrompt('Include playground application for development?', true)
   const includeGithubCi = await togglePrompt('Include GitHub CI configuration?', !!githubPath)
   const includePkgPrNew = includeGithubCi && await togglePrompt('Include pkg.pr.new in CI configuration?', false)
+  const includeNpmPublish = await togglePrompt('Include GitHub configuration for publishing to npm?', !!githubPath)
   const includeExamples = await togglePromptIf(extended, 'Include example code?', true, 'Yes', 'No, just configs')
   const includeAtAliases = await togglePromptIf(extended, 'Configure @ as an alias for src?')
   const includeTestVariable = await togglePromptIf(extended, 'Configure global __TEST__ variable?')
@@ -345,6 +347,7 @@ async function init() {
     includeVitest,
     includeGithubCi,
     includePkgPrNew,
+    includeNpmPublish,
     includeAtAliases,
     includeTestVariable,
     includeTailwind,
@@ -377,6 +380,10 @@ async function init() {
     copyTemplate('ci', config)
   }
 
+  if (config.includeNpmPublish) {
+    copyTemplate('npm-publish', config)
+  }
+
   if (config.includeTailwind) {
     copyTemplate('tailwind', config)
   }

packages/create-vue-lib/src/template/ci/config/.github/workflows/ci.yml.ejs

@@ -3,16 +3,13 @@ name: CI
 on:
   push:
     branches:
-      - main
+      - '**'
   pull_request:
     branches:
-      - main
+      - '**'
 
 jobs:
   ci:
-<%_ if (config.githubPath) { _%>
-    if: github.repository == '<%- config.githubPath %>'
-<%_ } _%>
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -40,5 +37,6 @@ jobs:
 <%_ } _%>
 <%_ if (config.includePkgPrNew) { _%>
       - name: Release
+        if: github.repository == '<%- config.githubPath %>'
         run: pnpx pkg-pr-new publish --commentWithSha --pnpm --packageManager=pnpm,npm,yarn './<%- config.packagesDir %><%- config.mainPackageDirName %>'
 <%_ } _%>

packages/create-vue-lib/src/template/gh-pages/config/.github/workflows/pages.yml.ejs

@@ -2,13 +2,18 @@
 name: Deploy to GitHub Pages
 
 on:
-  # Runs on pushes targeting the default branch
-  push:
-    branches:
-      - main
+<%_ if (config.includeNpmPublish) { _%>
+  # Allows the workflow to be triggered from other workflows
+  workflow_call:
+
+<%_ } _%>
+  # Run on pushes targeting the `main` branch
+  # push:
+  #   branches:
+  #     - main
 <%_ if (config.includePlayground) { _%>
-    paths-ignore:
-      - '<%- config.packagesDir %>playground/**'
+  #   paths-ignore:
+  #     - '<%- config.packagesDir %>playground/**'
 <%_ } _%>
 
   # Allows you to run this workflow manually from the Actions tab
@@ -28,6 +33,9 @@ concurrency:
 jobs:
   # Single deploy job since we're just deploying
   deploy:
+<%_ if (config.githubPath) { _%>
+    if: github.repository == '<%- config.githubPath %>'
+<%_ } _%>
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

packages/create-vue-lib/src/template/npm-publish/config/.github/workflows/publish.yml.ejs

@@ -0,0 +1,47 @@
+# Publish package to the npm registry
+name: Publish package to npm
+
+on:
+  # Run the workflow when a new tag is pushed starting with `v`
+  # push:
+  #  tags:
+  #    - 'v*'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: read
+<%_ if (config.includeGithubPages) { _%>
+  pages: write
+<%_ } _%>
+  id-token: write
+
+jobs:
+  publish:
+<%_ if (config.githubPath) { _%>
+    if: github.repository == '<%- config.githubPath %>'
+<%_ } _%>
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Install pnpm
+        uses: pnpm/action-setup@v5
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install dependencies
+        run: pnpm install
+      - name: Build
+        run: pnpm --filter "<%- config.scopedPackageName %>" run build
+      - name: Publish
+        run: pnpm --filter "<%- config.scopedPackageName %>" publish
+<%_ if (config.includeGithubPages) { _%>
+  docs:
+    needs: publish
+    uses: ./.github/workflows/pages.yml
+<%_ } _%>

packages/docs/src/publishing.md

@@ -102,4 +102,14 @@ It's common to create a release on GitHub when publishing a package. This includ
 
 ## Automating the process
 
-This scaffolding tool doesn't currently have any support for automating this process, but you can find various examples of automation scripts if you look through the GitHub repos for large projects.
+Several parts of the publishing process can be automated. You can find various examples of automation scripts if you look through the GitHub repos for large projects.
+
+This scaffolding tool provides configuration for using *trusted publishing* via a GitHub Action. It will be included if you answered `Yes` to the question *[Include GitHub configuration for publishing to npm?](questions#include-npm-publish)*.
+
+The workflow configuration is in `.github/workflows/publish.yml`. You'll also need to enable trusted publishing in the settings for your package on the npm registry:
+
+- https://docs.npmjs.com/trusted-publishers
+
+The first time you publish your package you'll need to do it manually, then you can enable trusted publishing for subsequent releases.
+
+You should check the contents of `publish.yml` to ensure you understand what it's doing. It will build and publish the package, but it won't handle any other part of the release process. The other steps, such as updating the version number in `package.json`, are still down to you.

packages/docs/src/questions.md

@@ -54,6 +54,7 @@
 <span class="check">✔</span> <a href="#include-playground">Include playground application for development? … No / Yes</a>
 <span class="check">✔</span> <a href="#include-github-ci">Include GitHub CI configuration? … No / Yes</a>
 <span class="check">✔</span> <a href="#include-pkg-pr-new">Include pkg.pr.new in CI configuration? … No / Yes</a>
+<span class="check">✔</span> <a href="#include-npm-publish">Include GitHub configuration for publishing to npm? … No / Yes</a>
 <span class="check">✔</span> <a href="#include-examples">Include example code? … No, just configs / Yes</a>
 <span class="check">✔</span> <a href="#configure-src-alias">Configure @ as an alias for src? … No / Yes</a>
 <span class="check">✔</span> <a href="#configure-test-variable">Configure global __TEST__ variable? … No / Yes</a></pre>
@@ -141,7 +142,7 @@ The GitHub path should be in the form `username/repo-name`.
 
 For example, this project has its repository at `https://github.com/skirtles-code/create-vue-lib`, so the GitHub path is `skirtles-code/create-vue-lib`.
 
-While answering this question is optional, it can be especially useful if you intend to use GitHub Pages to host your documentation, as the generated configuration files will be much closer to their final form.
+While answering this question is optional, it can be especially useful if you intend to use GitHub Pages to host your documentation, as the generated configuration files will be much closer to their final form. It is also used in some of the workflow configurations for GitHub Actions to help ensure they don't run on forks.
 
 ## Include Tailwind CSS?{#include-tailwind-css}
 
@@ -221,22 +222,34 @@ The playground application will use your library direct from the source code, wi
 
 ## Include GitHub CI configuration?{#include-github-ci}
 
-Continuous Integration (CI) is used to help catch problems as soon as they occur.
+*Continuous integration* (CI) is used to help catch problems as soon as they occur.
 
-This option will include a GitHub Actions configuration for a CI workflow. It will run the `lint`, `type-check`, `build` and `test:unit` targets from the `scripts` section of the root `package.json`. The workflow is triggered by any PRs opened against the `main` branch, as well as when changes are pushed to `main`.
-
-If a [GitHub path](#github-path) has been provided, the job will be configured so that it only runs for that specific fork.
+This option will include a GitHub Actions configuration for a CI workflow. It will run the `lint`, `type-check`, `build` and `test:unit` targets from the `scripts` section of the root `package.json`. The workflow is triggered when a PR is opened or when new commits are pushed to a branch.
 
 ## Include pkg.pr.new in CI configuration?{#include-pkg-pr-new}
 
 :::info NOTE
 You'll only see this question if you chose to include GitHub CI configuration.
 :::
 
-[pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) allows for continuous releases. Every PR and every commit to `main` will be published as a package on pkg.pr.new, which is similar to the npm registry but with each 'release' tied to a specific commit rather than a version number. This allows changes to be installed and tested before they're merged or released to npm.
+[pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) allows for *continuous releases*. Every PR and every commit to a branch will be published as a package on pkg.pr.new, which is similar to the npm registry but with each 'release' tied to a specific commit rather than a version number. This allows changes to be installed and tested before they're merged or released to npm.
 
 You'll also need to install the [pkg.pr.new GitHub App](https://github.com/apps/pkg-pr-new) and enable it on your GitHub repository.
 
+## Include GitHub configuration for publishing to npm?{#include-npm-publish}
+
+The recommended way to publish a package to the npm registry is via *trusted publishing*:
+
+- https://docs.npmjs.com/trusted-publishers
+
+If you'd like to publish your package using a GitHub Action then select this option. It will include a suitable workflow in `.github/workflow/publish.yml` with trusted publishing enabled.
+
+By default, this workflow will only run when it is triggered manually, via the **Actions** tab of your GitHub repository.
+
+You will also need to configure trusted publishing for your package on the npm registry. This can only be done for packages that already exist, so the first release of your package won't be able to use the automated workflow.
+
+- See also: [Publishing to npm](publishing)
+
 ## Include example code?{#include-examples}
 
 :::info NOTE

packages/docs/src/why.md

@@ -32,7 +32,7 @@ The project's root `package.json` uses `preinstall` and `postinstall` hooks. It'
 
 ## TypeScript configuration
 
-The TypeScript configuration is mostly done of a per-package basis. The configuration files are closely based on the files created by `create-vue`.
+The TypeScript configuration is mostly done on a per-package basis. The configuration files are closely based on the files created by `create-vue`.
 
 A root-level `tsconfig.json` is only created if ESLint is included. That is just used to check `eslint.config.ts`, which is at the root of the project. There currently aren't any other TS files that live outside the sub-packages.
 
@@ -112,9 +112,27 @@ For `__TEST__` we replace the value with a simple `true` or `false`, which can b
 
 For `__DEV__` it's a little more complicated, because in some builds we replace it with `!(process.env.NODE_ENV === "production")`. This allows the downstream bundler to make the decision about what mode we're in. We can't use `define` for a complex value like this, so `@rollup/plugin-replace` is used instead.
 
-## `pages.yml`
+## GitHub Action workflows
 
-The file `.github/worksflows/pages.yml` configures the GitHub Pages workflow for the documentation. The exact name of the file is not important, GitHub will run all workflows configured in `.github/workflows`.
+The files in `.github/workflows` are workflow configurations for GitHub Actions. The exact names of these files aren't important, GitHub will load all workflows in that directory and run them as needed.
+
+Different workflows need to run at different times. This is controlled via the `on` setting, which specifies exactly which events should trigger the workflow. Some events can also be filtered further to target specific branches, tags or file paths within the repo.
+
+It's also necessary to consider how workflows should behave on forks. If other contributors fork your repo on GitHub then they'll also copy the workflow configurations. For a CI workflow, building and testing changes on the fork is probably what you'd want. But a workflow for deploying the documentation probably shouldn't be enabled on a fork.
+
+Where relevant, the workflows will try to use an `if` check on `github.repository` to ensure that they only run on the original repo. This can only be configured correctly if you provided a [GitHub path](questions#github-path) when running the scaffolding tool.
+
+### `ci.yml`
+
+Depending on exactly which options you picked, the CI workflow will build the project (including the docs and playground), run the tests, linting and type checking. It's also responsible for [deploying to pkg.pr.new](questions#include-pkg-pr-new).
+
+### `pages.yml`
+
+:::info NOTE
+You'll also need to enable GitHub Pages in the settings for your repo.
+:::
+
+The file `.github/worksflows/pages.yml` configures the GitHub Pages workflow for the documentation.
 
 The configuration is similar to those found at:
 
@@ -123,11 +141,25 @@ The configuration is similar to those found at:
 
 pnpm is enabled in the configuration, but a specific version isn't specified as we're using the `packageManager` option in `package.json`.
 
-The workflow is configured to run on the `main` branch. You'd typically want the documentation to reflect the latest release, so whether `main` is an appropriate choice will depend on your release process.
+The workflow can be run manually from the **Actions** tab in GitHub. If you opted to [include a workflow for npm publishing](questions#include-npm-publish) then that will also trigger deployment of the docs. This ensures the latest docs are deployed when a new release is published to the npm registry.
 
-The [`paths-ignore`](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore) setting can be used to avoid running GitHub Pages for changes that don't impact the documentation. The default configuration will only ignore the playground package. Trying to be really precise about what changes trigger the workflow is error-prone and the small gains usually aren't worth the extra effort.
+If you want to deploy the docs for all commits to `main` then you'll need to edit `pages.yml` to enable that. The relevant configuration is already included, it's just commented out. This can lead to the docs for new features being released before they're published to npm, so it should only be enabled if it makes sense for your branching strategy and release process.
 
-You'll also need to enable GitHub Pages in the settings for your repo.
+### `publish.yml`
+
+:::info NOTE
+You'll also need to enable *trusted publishing* in the settings for your package on the npm registry.
+:::
+
+The file `.github/worksflows/publish.yml` configures a GitHub workflow to release your package to the npm registry.
+
+By default, this workflow will not run automatically. It must be run manually from the **Actions** tab in your GitHub repository. This is intentionally cautious but can easily be changed. A common approach is to tag each release with a git tag and to trigger the workflow whenever a new tag is added to the repo. There's example configuration for that in `publish.yml`.
+
+The workflow will build the package and publish it to the npm registry. It avoids building the other packages, such as the docs or playground, and won't run the tests or linting checks. Those checks are already performed by the CI workflow and aren't strictly required to make a release. It is left to your discretion to decide whether your codebase is ready for a release.
+
+Running the workflow won't make any changes to the code, such as bumping the version number. You'll need to ensure the version is set correctly in the relevant `package.json` before running the workflow.
+
+- See also: [Publishing to npm](publishing)
 
 ## `jiti`