Token Package Publishing

Token package publishing distributes design tokens as consumable packages through package registries. Publishing enables version management, dependency tracking, and standardized installation. Proper publishing practices ensure consumers can reliably install and update tokens.

What Is Token Package Publishing

Token package publishing is the process of packaging token outputs and metadata for distribution through npm or other package registries. Published packages allow consumers to install tokens with standard tooling (npm install), declare dependencies, and receive updates through normal package management workflows.

How Token Package Publishing Works

Package configuration:

// package.json
{
  "name": "@company/design-tokens",
  "version": "2.3.0",
  "description": "Design tokens for Company design system",
  "main": "dist/js/tokens.js",
  "module": "dist/js/tokens.esm.js",
  "types": "dist/js/tokens.d.ts",
  "style": "dist/css/tokens.css",
  "exports": {
    ".": {
      "import": "./dist/js/tokens.esm.js",
      "require": "./dist/js/tokens.js",
      "types": "./dist/js/tokens.d.ts"
    },
    "./css": "./dist/css/tokens.css",
    "./scss": "./dist/scss/tokens.scss"
  },
  "files": [
    "dist"
  ],
  "publishConfig": {
    "access": "public"
  }
}

Build before publish:

{
  "scripts": {
    "prepublishOnly": "npm run build && npm run test"
  }
}

Publishing workflow:

# Update version
npm version minor

# Publish to registry
npm publish

# Or with scoped package
npm publish --access public

Automated publishing with CI:

# GitHub Actions
on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Key Considerations

• Package should only include built artifacts
• Entry points should cover common usage patterns
• TypeScript types improve developer experience
• README should include installation and usage
• Changelog should accompany releases
• Semantic versioning indicates change impact
• Prerelease versions enable testing
• Registry choice affects availability

Common Questions

What should packages include?

Packages should include everything consumers need, nothing more.

Include:

dist/
  css/
    tokens.css
    tokens.min.css
  js/
    tokens.js
    tokens.esm.js
    tokens.d.ts
  scss/
    tokens.scss
    _variables.scss
README.md
LICENSE
CHANGELOG.md

Exclude (via .npmignore or files field):

src/              # Source tokens
build/            # Build scripts
node_modules/
.github/
*.config.js
tests/

Package.json files field:

{
  "files": [
    "dist",
    "README.md",
    "CHANGELOG.md"
  ]
}

How should private registries be used?

Private registries serve internal tokens.

npm private packages:

{
  "name": "@company/tokens",
  "publishConfig": {
    "registry": "https://npm.company.com"
  }
}

GitHub Packages:

{
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

Artifactory:

npm config set registry https://artifactory.company.com/api/npm/npm-local
npm publish

Consumer configuration:

# .npmrc
@company:registry=https://npm.company.com
//npm.company.com/:_authToken=${NPM_TOKEN}

How should prereleases be handled?

Prereleases enable testing before stable release.

Prerelease versions:

# Alpha (early testing)
npm version 2.4.0-alpha.1
npm publish --tag alpha

# Beta (feature complete, testing)
npm version 2.4.0-beta.1
npm publish --tag beta

# Release candidate (ready for final testing)
npm version 2.4.0-rc.1
npm publish --tag rc

Installing prereleases:

# Explicit version
npm install @company/tokens@2.4.0-beta.1

# Via tag
npm install @company/tokens@beta

Promoting to stable:

# When ready, publish stable version
npm version 2.4.0
npm publish

# latest tag automatically applied

Summary

Token package publishing distributes tokens through registries for standardized installation and updates. Package configuration specifies entry points for different module systems and includes only built artifacts. Automated CI publishing ensures consistent releases. Private registries serve internal tokens with appropriate authentication. Prerelease versions enable testing new token versions before stable release.