Packaging with npm¶

Exercise packaging-npm-annex.pdf · PDF

Run npm install in your project and read the last lines: hundreds of packages. How many of those did you write? None. Each one is something somebody packed and published, and your app stands on all of them.

On 22 March 2016, a developer called Azer Koçulu removed his packages from npm after a dispute over a name. One of them was left-pad: 11 lines that add spaces to the left of a string. Within hours, thousands of projects around the world could not be installed or built, among them Babel and React, because something they depended on depended on those 11 lines. npm restored the package and changed its rules. Publishing is a promise to strangers. On this page you make your first box, and learn to read what is inside before sealing it.

The route of a brick¶

A package is a folder of files plus a package.json, compressed so other projects can install it. The compressed file is called a tarball (.tgz). The registry is the shop where packages are published: registry.npmjs.org.

flowchart LR
    S["<b>src/lib/</b><br>the workshop"] -->|"svelte-package"| D["<b>dist/</b><br>a clean copy"]
    D -->|"npm pack"| T["<b>.tgz</b><br>the sealed box"]
    T -->|"npm publish"| R["<b>registry</b><br>the shop"]
    R -->|"npm install"| N["<b>node_modules/</b><br>another project"]

We stop at the box. npm install ./notebox-ui-0.1.0.tgz installs straight from the file: the same result for the buyer, no account needed, and nothing public that you cannot take back.

Pack it¶

1. Install¶

npm install -D @sveltejs/package publint

publint checks your package for packaging mistakes. Check too that src/lib/index.js exports your components, as you did in Methods, snippets and events.

2. Write the label¶

Edit package.json. Remove "private": true, because npm refuses to publish a private package. Then set a real name and version, and add these fields to what you already have:

{
    "name": "notebox-ui",
    "version": "0.1.0",
    "description": "NoteBox UI: reusable Svelte 5 components",
    "license": "MIT",
    "scripts": {
        "prepack": "svelte-kit sync && svelte-package && publint"
    },
    "files": ["dist", "!dist/**/*.test.*", "!dist/**/*.stories.*", "!dist/**/*.mdx"],
    "sideEffects": ["**/*.css"],
    "svelte": "./dist/index.js",
    "types": "./dist/index.d.ts",
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
            "svelte": "./dist/index.js"
        },
        "./tokens.css": "./dist/tokens.css"
    },
    "peerDependencies": {
        "svelte": "^5.0.0"
    }
}

A peer dependency is a package your library needs but does not bring. It says: use the one in the buyer's project. If Svelte were a normal dependency, the app could end up with two copies of it.

3. Seal it¶

npm pack

Read the output, line by line. This is the moment of truth:

src/lib -> dist
Running publint v0.3.25 for notebox-ui...
Packing files with `npm pack`...
Linting...
All good!
npm notice Tarball Contents
npm notice 1.1kB README.md
npm notice 1.6kB dist/assets/favicon.svg
npm notice 1.3kB dist/components/Button.svelte
npm notice 1.1kB dist/components/Button.svelte.d.ts
npm notice 1.9kB dist/components/NoteRow.svelte
npm notice 1.5kB dist/components/UndoBar.svelte
...
npm notice 268B dist/index.js
npm notice 312B dist/tokens.css
npm notice 1.5kB package.json

Is there anything in this box that should not be there? Look again: dist/assets/favicon.svg. Nobody put it there on purpose. The project template left a favicon in src/lib/assets/, and everything in src/lib is copied.

Move the file out of the library, to src/assets/favicon.svg, and change the import in src/routes/+layout.svelte:

import favicon from '../assets/favicon.svg';

Run npm pack again, and the leftover is gone. Is anything missing? No stories, no tests: files did its job.

4. Be the customer¶

Use a second, empty project (npx sv create consumer, minimal template) in a folder next to notebox:

npm install ../notebox/notebox-ui-0.1.0.tgz

<script>
    import { Button, NoteRow } from 'notebox-ui';
    import 'notebox-ui/tokens.css';

    let count = $state(0);
</script>

<NoteRow title="Installed from a package" preview="Clicked {count} times" />
<Button onclick={() => count++}>Click me</Button>

Run npm run dev: a NoteBox button, in a project that has never seen Button.svelte. Type <Button variant=" and the editor offers the three variants. That is the .d.ts file, generated from your JSDoc.

A package that only works on its author's machine is not a package. So give your .tgz to a classmate, and ask them to render two of your components using only your Storybook Docs.

Both dist/ and *.tgz are build outputs: add them to .gitignore.

Which number moves?¶

Semantic versioning (semver) writes a version as MAJOR.MINOR.PATCH. The number is a message to the people who use your library: it tells them whether updating is safe.

Button gets a new optional prop, size="lg"? Minor. What if the default of size changes from md to sm? Major: every <Button> without size now looks different, and nobody's code changed. A default is part of the contract.

Publishing for real¶

Nobody in the class publishes to the public registry: names are first come, first served, and accounts need personal e-mail addresses. But this is the rest of the route:

That last rule, and the limits on unpublishing, exist because of those 11 lines. Today a package can only be removed freely in its first 72 hours, and only if nothing else in the registry depends on it. After that, stricter conditions apply.

Key takeaways¶

• The route: src/lib, svelte-package, dist, npm pack, tarball, npm publish, registry, npm install, node_modules.
• files decides what goes in the box and exports decides what can be imported. Read the listing every time.
• A Svelte package ships source files. Svelte is a peer dependency: the buyer brings the compiler.
• prepack rebuilds and checks the package automatically before every npm pack.
• Semantic versioning: patch for a fix, minor for something new, major for something that breaks. Changing a default is a major change.
• A published version can never be overwritten. Publish the next one.

Quick check¶

The bricks are in the box. Now you have to build something with them: Workshop and revision.