Releasing Kimesh

Overview

Kimesh uses automated GitHub Actions workflows for releasing packages to npm. This guide covers the release process for maintainers.

Release Types

Production Release

• Triggered by pushing a version tag (e.g., v1.0.0)
• Publishes all packages to npm with @latest tag
• Includes npm provenance for supply chain security

Nightly Release

• Triggered automatically on every push to main branch
• Publishes packages with -nightly suffix (e.g., @kimesh/kit-nightly)
• Uses @nightly tag on npm

PR Preview

• Triggered automatically on pull requests
• Uses pkg-pr-new for instant preview packages
• Allows testing changes before merging

How to Release

1. Prepare the Release

# Bump version (choose one)
bun run bump patch  # 0.0.x → bug fixes
bun run bump minor  # 0.x.0 → new features
bun run bump major  # x.0.0 → breaking changes

2. Commit and Tag

git add .
git commit -m "chore: release v1.0.0"
git tag v1.0.0
git push origin main --tags

3. Monitor the Release

• Go to GitHub Actions tab
• Watch the "Release" workflow
• Check npm for published packages

Packages Published

Core Packages (packages/)

Package	Description
kimesh	Umbrella package (re-exports router-runtime, query, head)
@kimesh/kit	Build-time engine: config loading, module system, Vite plugin
@kimesh/cli	CLI commands (dev, build, prepare, init, layer)
@kimesh/router-runtime	Runtime router: components, composables, middleware, plugins
@kimesh/router-generator	File-based route generation from directory structure
@kimesh/query	Data fetching: $fetch, loaders, TanStack Query integration
@kimesh/head	Head meta management: useHead, useSeoMeta, head components
@kimesh/auto-import	OXC-powered auto-import system with layer support
@kimesh/layers	Layer discovery, resolution, and configuration merging
@kimesh/shared	Shared utilities and types across packages
create-kimesh	Project scaffolding tool (bun create kimesh)

Official Modules (modules/)

Module	Description
@kimesh/pinia	Pinia state management integration
@kimesh/tailwindcss	TailwindCSS integration with layer support
@kimesh/shadcn	shadcn/ui component auto-registration

Setup Requirements

NPM Token

1. Generate token at npmjs.com → Access Tokens
2. Add to GitHub repo: Settings → Secrets → Actions → NPM_TOKEN

Repository Settings

• Ensure id-token: write permission is enabled for OIDC provenance

Scripts Reference

Script	Command	Description
Release	bun run release	Publish all packages (CI only)
Bump Patch	bun run bump patch	Increment patch version
Bump Minor	bun run bump minor	Increment minor version
Bump Major	bun run bump major	Increment major version
Nightly	bun run bump:nightly	Generate nightly version

Troubleshooting

Release Failed

1. Check GitHub Actions logs
2. Ensure NPM_TOKEN is valid
3. Verify package.json has correct publishConfig

Package Not Found

• Nightly packages use -nightly suffix
• Install with: npm i @kimesh/kit-nightly@nightly