Veřejný npm a Bun balíček od nuly

Veřejně instalovatelný npm/bun balíček není jen složka s kódem a příkaz publish. Ukážeme si strukturu repozitáře, build do ESM/CJS, typy, exporty, test lokální instalace, publikaci do registru a chyby, které poznáte až ve chvíli, kdy balíček začne používat někdo mimo váš projekt.

Kdy má smysl knihovnu publikovat veřejně

Publikace má smysl, když řešíte opakovatelný problém, ne když jen odkládáte interní utility stranou. Dobrý kandidát je validátor, wrapper nad API, malá UI knihovna nebo CLI nástroj, který umí použít více projektů bez znalosti vašeho monolitu.

Naopak bychom nepublikovali kód pevně svázaný s jednou doménou, databázovým schématem nebo tajnými konfiguracemi. Veřejný npm/bun balíček musí mít čisté rozhraní, nulové tajné hodnoty v historii Gitu a dokumentované předpoklady prostředí.

U klientských projektů podobné knihovny často vzniknou jako vedlejší produkt vývoje. Pokud stavíte více aplikací nad stejným stackem, vyplatí se oddělit stabilní část do balíčku a zbytek ponechat v aplikaci. U webových produktů to řešíme i v rámci vývoje webových aplikací.

Struktura balíčku pro npm registry i Bun

Začněte minimální strukturou: src pro zdrojové soubory, dist pro build, package.json, README.md, testy a licenci. Nepublikujte zdrojový chaos. Registry má dostat jen to, co uživatel reálně potřebuje k instalaci a běhu.

Bun umí instalovat balíčky z npm registru, takže často publikujete jednou a konzumujete z obou světů. Rozdíl je hlavně v lokálním workflow: Bun může rychleji instalovat a spouštět skripty, ale metadata balíčku pořád řídí hlavně package.json.

{
  "name": "@scope/slugify-cz",
  "version": "0.1.0",
  "description": "Small Czech slug generator for Node, Bun and browsers.",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "files": ["dist", "README.md", "LICENSE"],
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "prepublishOnly": "npm run build"
  }
}

Pole files je podceňované. Bez něj snadno odešlete testovací data, lokální konfigurace nebo zdrojové mapy, které nechcete podporovat. Před publikací vždy spusťte npm pack a podívejte se, co by se skutečně nahrálo do registru.

ESM, CommonJS a typy bez bolesti uživatelů

Největší zdroj problémů bývá kompatibilita modulů. Moderní runtime preferuje ESM, ale mnoho starších Node projektů stále používá CommonJS. Pokud knihovna není extrémně malá, doporučujeme buildovat obě varianty a přes exports řídit, co kdo dostane.

TypeScript typy publikujte jako první třídu API. Uživatelé balíčku často nejdřív čtou autocomplete a až potom dokumentaci. Pokud typy neodpovídají runtime chování, rozbijete důvěru rychleji než chybou v README.

export type SlugifyOptions = {
  lower?: boolean;
  separator?: "-" | "_";
};

export function slugifyCz(input: string, options: SlugifyOptions = {}): string {
  const separator = options.separator ?? "-";
  const lower = options.lower ?? true;

  const normalized = input
    .normalize("NFD")
    .replace(/[\u0300-\u036f]/g, "")
    .replace(/[^a-zA-Z0-9]+/g, separator)
    .replace(new RegExp(`${separator}+$|^${separator}+`, "g"), "");

  return lower ? normalized.toLowerCase() : normalized;
}

U utility funkcí držte API nudné a stabilní. Jedna výchozí funkce a pojmenované typy bývají lepší než magie s globální konfigurací. U veřejného balíčku je zpětná kompatibilita důležitější než elegantní refaktor interního kódu.

Lokální ověření instalace před publikací

Nestačí spustit testy v repozitáři balíčku. Potřebujete simulovat cizí projekt, který balíček instaluje z archivu. Tím odhalíte chybějící soubory v files, špatné cesty v exports i nefunkční typové deklarace.

Praktický postup je jednoduchý: build, npm pack, instalace vzniklého tarballu do prázdného projektu a import v Node i Bunu. Teprve když projde tento test, má veřejný npm/bun balíček reálnou šanci fungovat mimo váš počítač.

npm run build
npm pack

mkdir /tmp/pkg-check
cd /tmp/pkg-check
npm init -y
npm install /path/to/scope-slugify-cz-0.1.0.tgz
node -e "import('@scope/slugify-cz').then(m => console.log(m.slugifyCz('Žluťoučký kůň')))"

bun init -y
bun add /path/to/scope-slugify-cz-0.1.0.tgz
bun -e "import { slugifyCz } from '@scope/slugify-cz'; console.log(slugifyCz('Příliš žluťoučký'))"

Pokud balíček obsahuje CLI, testujte i binární příkaz. Chyby v shebangu nebo v poli bin se v běžných unit testech neukážou. Stejně tak testujte čistou instalaci bez lokálních symlinků, protože npm link umí skrýt problém s distribučními soubory.

Publikace do registru a bezpečné verzování

Pro veřejnou distribuci použijete npm registry. Vytvořte účet, zapněte dvoufaktorové ověření a u organizací publikujte pod scoped názvem, například @firma/nazev. Oficiální postup najdete v dokumentaci npm pro scoped public packages.

Verzování držte podle SemVer: patch pro opravu bez změny API, minor pro zpětně kompatibilní funkce, major pro breaking change. Není to formalita. Správná verze rozhoduje, jestli uživatel dostane bezpečný update, nebo rozbitou produkci.

npm login
npm version patch
npm publish --access public

# kontrola po publikaci
npm view @scope/slugify-cz version
npm install @scope/slugify-cz
bun add @scope/slugify-cz

Bun používá npm ekosystém a příkaz bun add běžně instaluje balíčky z npm registru. Detaily chování balíčkovacího nástroje popisuje oficiální dokumentace Bun install. Při publikaci proto řešíte hlavně kompatibilitu výstupu, ne druhý registr.

README, licence a údržba veřejného balíčku

README není marketingový leták. Má obsahovat instalaci pro npm i Bun, nejkratší použitelný příklad, popis API, podporované runtime a poznámky k chybám. Uživatel musí během minuty pochopit, jestli je balíček pro jeho projekt bezpečná volba.

Licenci vyberte vědomě. MIT je běžná pro malé open-source knihovny, ale nehodí se automaticky pro každý firemní kód. Pokud balíček vznikl pro klienta, ověřte vlastnictví práv a schválení publikace dřív, než cokoli nahrajete do registru.

Údržba začíná ve chvíli publikace. Sledujte issues, opravujte bezpečnostní hlášení a neprovádějte breaking změny potichu. U malých knihoven doporučujeme raději úzký rozsah a stabilitu než rychlé přidávání funkcí, které z balíčku udělají nečitelný framework.

Automatizace releasů přes CI bez ruční magie

Ruční publikace je v pořádku pro první verzi. Jakmile balíček používá více projektů, vyplatí se release pipeline. CI má spustit testy, build, kontrolu obsahu balíčku a publikaci jen z tagu nebo schváleného release procesu.

Token pro publikaci neukládejte do repozitáře. Patří do secrets v GitHub Actions, GitLabu nebo jiném CI. Dobrý release proces je nudný: stejné kroky, stejný výstup, minimum ručního rozhodování a jasný audit, kdo vydal jakou verzi.

name: Release package

on:
  release:
    types: [published]

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

U veřejných knihoven navíc zvažte provenance, podepisování releasů a omezený token jen pro publikaci daného balíčku. Nejde o paranoidní detail. Supply-chain útoky se často neptají, jestli má knihovna deset uživatelů nebo deset tisíc.

Co si odnést před prvním npm publish

Nejprve navrhněte malé API, potom vyřešte build, typy, exporty a lokální instalaci z tarballu. Teprve potom publikujte. Tento postup je pomalejší než rychlé npm publish, ale výrazně snižuje počet nekompatibilních verzí, které už nejdou vzít zpět beze škod.

Veřejně instalovatelný npm/bun balíček je závazek vůči lidem, kteří nevidí váš kontext. Když jim dáte čisté rozhraní, kompatibilní výstup, srozumitelnou dokumentaci a bezpečný release proces, bude knihovna použitelná i mimo původní projekt.