This page documents the TypeScript pre-release publishing workflows that publish packages to npm under special dist-tags. The repository maintains two distinct pre-release channels:
@next dist-tag): Automated daily builds from the main branch for continuous integration and bleeding-edge testing.@insiders dist-tag): On-demand builds for early adopters, editor integrations, and coordinated releases.Both workflows follow similar patterns: configure version, run tests, build LKG, and publish to npm. This page covers the technical implementation of these workflows within GitHub Actions.
hereby build task system, see page 10.1.Both publishing workflows share the same fundamental structure but differ in trigger conditions, frequency, and version scheme.
Publishing Workflow Comparison
| Property | Nightly | Insiders |
|---|---|---|
| Workflow file | .github/workflows/nightly.yaml | .github/workflows/insiders.yaml |
| npm dist-tag | next | insiders |
| Trigger | Daily cron (0 7 * * *) + manual | Manual + repository dispatch |
| Frequency | Automated daily | On-demand only |
| Version task | hereby configure-nightly | hereby configure-insiders |
| Use case | Automated testing, downstream CI | Editor integrations, coordinated releases |
| Repository guard | microsoft/TypeScript only | microsoft/TypeScript only |
Sources: .github/workflows/nightly.yaml1-7 .github/workflows/insiders.yaml1-6
The nightly workflow is defined in .github/workflows/nightly.yaml It publishes TypeScript to npm under the next dist-tag on a daily schedule.
Trigger Conditions
.github/workflows/nightly.yaml3-7
| Trigger | Description |
|---|---|
schedule (cron: 0 7 * * *) | Daily at 7:00 AM UTC (approximately midnight Pacific Time). |
workflow_dispatch | Manual trigger from GitHub Actions UI for emergency or ad-hoc builds. |
The cron schedule ensures a fresh build is available every day for continuous integration systems and developers testing against the latest changes.
Sources: .github/workflows/nightly.yaml3-7
The nightly workflow consists of two sequential jobs: test and publish.
Workflow: Nightly Publishing Pipeline
Sources: .github/workflows/nightly.yaml18-66
test Job.github/workflows/nightly.yaml19-37
The test job validates the nightly build before publishing:
main branch.lts/* version.package.json packageManager field package.json112npm ci to install dependencies with exact versions from lockfile.npx hereby configure-nightly to transform version strings in working copy.npm test to execute full test suite.If tests fail, the publish job is skipped and no package is published.
Sources: .github/workflows/nightly.yaml19-37 package.json112
publish Job.github/workflows/nightly.yaml39-66
The publish job requires the test job to succeed via needs: [test]. It performs an independent build and publishes to npm:
registry-url: https://registry.npmjs.org/ for npm authentication.npm whoami to verify npm credentials before proceeding.npm ci to install dependencies.npx hereby configure-nightly to set nightly version.npx hereby LKG to compile Last Known Good artifacts into ./lib/.node ./scripts/addPackageJsonGitHead.mjs package.json to inject git SHA.npm publish --tag next using NODE_AUTH_TOKEN secret.Sources: .github/workflows/nightly.yaml39-66
The insiders workflow is defined in .github/workflows/insiders.yaml It publishes TypeScript to npm under the insiders dist-tag on demand.
Trigger Conditions
.github/workflows/insiders.yaml3-6
| Trigger | Description |
|---|---|
workflow_dispatch | Manual trigger from GitHub Actions UI. |
repository_dispatch (type: publish-insiders) | Programmatic trigger via GitHub API, typically used by TypeScript Bot. |
Unlike nightly, there is no scheduled trigger. Insiders builds are always explicitly requested by a human or automation.
Sources: .github/workflows/insiders.yaml3-6
The insiders workflow consists of two sequential jobs: test and publish.
Workflow: Insiders Publishing Pipeline
Sources: .github/workflows/insiders.yaml17-66
test Job.github/workflows/insiders.yaml18-36
The test job validates the insiders build before publishing:
lts/* version.package.json packageManager field.npm ci to install dependencies.npx hereby configure-insiders to transform version strings.npm test to execute full test suite.If tests fail, the publish job is skipped.
Sources: .github/workflows/insiders.yaml18-36
publish Job.github/workflows/insiders.yaml38-66
The publish job requires the test job to succeed via needs: test. It performs an independent build and publishes to npm:
registry-url: https://registry.npmjs.org/ for npm authentication.npm whoami verify credentials.npm ci to install dependencies.npx hereby configure-insiders to set insiders version.npx hereby LKG to compile Last Known Good artifacts into ./lib/.node ./scripts/addPackageJsonGitHead.mjs package.json to inject git SHA.npm publish --tag insiders using NODE_AUTH_TOKEN secret.Sources: .github/workflows/insiders.yaml38-66
Both workflows share the same core infrastructure for version configuration, artifact generation, and publishing.
Code Entity Map: Publishing Shared Infrastructure
Sources: .github/workflows/nightly.yaml .github/workflows/insiders.yaml package.json
| Task / Script | Role |
|---|---|
hereby configure-nightly | Modifies package.json and src/compiler/corePublic.ts to set nightly version (e.g., x.y.z-dev.YYYYMMDD). |
hereby configure-insiders | Modifies package.json and src/compiler/corePublic.ts to set insiders version (e.g., x.y.z-insiders.YYYYMMDD). |
hereby LKG | Compiles compiler source and copies built artifacts into ./lib/, creating the Last Known Good snapshot that gets packed into npm tarball. |
scripts/addPackageJsonGitHead.mjs | Injects git commit SHA into package.json gitHead field before publishing, making builds traceable to source. |
npm publish --tag <tag> | Publishes package to npm registry under specified dist-tag (next or insiders), leaving latest tag unaffected. |
Sources: .github/workflows/nightly.yaml60-63 .github/workflows/insiders.yaml60-63
The configure-nightly and configure-insiders tasks perform transformations on version string patterns in the following locations:
package.json: Update the version field package.json5src/compiler/corePublic.ts: Update version constants (e.g., version, versionMajorMinor) used by the compiler.tests/baselines/reference/api/typescript.d.ts: Update the version string in the baseline declaration file.These modifications ensure version consistency across package metadata, compiler internals, and test expectations.
Sources: .github/workflows/nightly.yaml36 .github/workflows/insiders.yaml35 src/compiler/corePublic.ts
The hereby LKG task is critical for publishing. It ensures that the artifacts in the lib/ directory are up-to-date with the current source code before they are packed into the npm tarball.
The package.json specifies which files are included in the published package:
bin/ package.json32lib/ package.json33LICENSE.txt, README.md, etc. package.json35-37Sources: package.json31-40 .github/workflows/nightly.yaml61
Both workflows declare permissions: contents: read .github/workflows/nightly.yaml10 .github/workflows/insiders.yaml9 This is the minimum permission required to check out the repository.
npm authentication uses the npm_token repository secret, passed as the NODE_AUTH_TOKEN environment variable .github/workflows/nightly.yaml65 The actions/setup-node action automatically configures .npmrc when registry-url is specified .github/workflows/nightly.yaml50
Both workflows include if: github.repository == 'microsoft/TypeScript' guards on all jobs .github/workflows/nightly.yaml21 .github/workflows/insiders.yaml20 This prevents the workflows from running on repository forks, protecting the npm_token secret from exposure in forked workflow runs.
Sources: .github/workflows/nightly.yaml21-65 .github/workflows/insiders.yaml20-65
While nightly and insiders publish directly to npm, release branches also generate releasable artifacts via .github/workflows/release-branch-artifact.yaml
Release Branch Artifact Pipeline
This workflow ensures that every push to a release branch produces a validated .tgz file ready for potential distribution.
Refresh this wiki