sk-az-tools/docs/PACKAGING.md

Developing hello-world (ESM) Summary

Minimal Layout

• package.json, README.md, src/index.js (ESM only).
• package.json uses "type": "module" and explicit exports.
• files allow-list to control shipped content.

Example package.json:

{
  "name": "hello-world",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": "./src/index.js"
  },
  "files": ["src", "README.md", "package.json"],
  "engines": {
    "node": ">=18"
  }
}

Example src/index.js:

export function helloWorld() {
  console.log("Hello World!!!");
}

Sub-modules (Subpath Exports)

• Expose sub-modules using explicit subpaths in exports.
• Keep public API small and intentional.

Example:

{
  "exports": {
    ".": "./src/index.js",
    "./greetings": "./src/greetings.js",
    "./callouts": "./src/callouts.js"
  }
}

exports vs files

• exports defines the public import surface (what consumers can import).
• files defines what gets packaged; supports globs and negation.

Example:

{
  "files": ["dist/**", "README.md", "!dist/**/*.map"]
}

Dev Workflow (Separate Repo, Live Updates)

• Use npm link for live-edit development across repos.

Publisher repo:

npm link

Consumer repo:

npm link hello-world

Notes:

• If you build to dist/, run a watch build so the consumer sees updates.
• Unlink when done:

npm unlink hello-world

Distribution as a .tgz Artifact

• Create a tarball with npm pack and distribute the .tgz file.
• Install directly from the tarball path.
• Use npm pack --dry-run to verify contents before sharing.
• The .tgz is written to the current working directory where npm pack is run.
• You can redirect output with --pack-destination (or pack-destination config).
• Ship package.json in the artifact, but exclude package-lock.json (keep it in the repo for development only).

Commands:

npm pack
npm install ./hello-world-1.0.0.tgz

Example with output directory:

npm pack --pack-destination ./artifacts