Skip to content

chore(distribution): make npm the primary release channel and keep JSR as fallback #22

Description

@Hebilicious

Goal

Make npm the primary publishing, installation, and documentation path for @hebilicious/cssforge. Retain JSR as a secondary/backup distribution channel, including a documented native-Deno option.

This consolidates the previously discussed installation/import-specifier and public CLI-entry-point work into one distribution change.

Starting point

In the audited revision (b7d5ee36fe53d819251b055d5e1ec3d384274ad8):

  • The release workflow explicitly skips npm publishing and publishes to JSR.
  • The package manifest already exposes built ESM, declarations, and a public ./cli export, but does not declare a bin executable.
  • The README defaults to JSR installation/imports and invokes tsx ./node_modules/@hebilicious/cssforge/src/cli.ts.

Proposed changes

  • Publish the built package to npm through the release workflow; use trusted publishing where supported by the selected setup.
  • Keep JSR publishing as a separate secondary step/job. Report secondary-channel failures clearly and allow retries without republishing an already-published npm version.
  • Add a public cssforge executable, backed by the built CLI, while preserving the existing ./cli export.
  • Make the default installation examples npm install --save-dev @hebilicious/cssforge and pnpm add -D @hebilicious/cssforge.
  • Use import { defineConfig } from "@hebilicious/cssforge" in default configuration and programmatic examples.
  • Document a package script such as "cssforge": "cssforge"; remove consumer instructions that reach into node_modules/.../src or depend on an undeclared tsx installation.
  • Move Deno/JSR instructions into an alternative-installation section.
  • Update both READMEs, configuration templates, agent-facing usage references, and the documentation-site work in feat(docs): add docs website #19.

Acceptance criteria

  • npm is the primary release channel and the default in installation, configuration, and CLI documentation.
  • JSR remains available and is documented as secondary, with a clear retry/failure policy.
  • The npm artifact includes working ESM exports, declarations, and an executable CLI with the correct shebang/entry-point behavior.
  • Supported Node versions and TypeScript-config loading requirements are explicit and tested.
  • CI builds and packs the package, installs that tarball in a clean temporary project, imports the public package, runs the installed CLI with --help, and generates CSS/JSON/TypeScript from a fixture.
  • Smoke tests cover npm and pnpm execution, including executable symlink/shim behavior; consumers do not need repository development dependencies.
  • The secondary JSR entry points receive their own smoke test.

Scope

Distribution and developer experience only. No new component-styling API, framework-specific runtime, or configuration-schema redesign.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions