How-to

Publishing Components

Publishing Bascik components allows teams and open-source authors to distribute reusable components as standard npm packages. Consuming projects copy those components into their codebase with bascik add.

The bascik.components contract

A component package is a regular npm package with a bascik.components field in its package.json pointing to the directory containing component files:

json 
{
  "name": "@acme/ui",
  "version": "1.0.0",
  "bascik": {
    "components": "./components"
  }
}

The directory path is relative to the package root. All component files (.html, paired .css, paired scripts) in that directory and its subdirectories are advertised for consumers to add.

Organize your component package repository with a clean components directory:

text 
my-component-package/
  package.json
  README.md
  LICENSE
  components/
    acme-button/
      acme-button.html
      acme-button.css
      acme-button.ts
    acme-card/
      acme-card.html
      acme-card.css
    acme-badge/
      acme-badge.html

Ensure the files field in package.json includes the components directory (e.g. "files": ["components"]), or that .npmignore does not exclude it when publishing.

Files are copied verbatim

Bascik does not run a build step or transformation pass when copying components with bascik add. Files land in the consumer's src/components/ directory exactly as published.

Because of this copy-in model:

  1. Do not rely on package-relative build steps: Write vanilla HTML, standard CSS, and TypeScript with erasable syntax only (a companion .ts or <script type="text/typescript">). The consumer's Bascik strips the types with no setup; enum, namespaces, and parameter properties fail their build.
  2. Component names come from filenames: Lowercase base filenames determine custom element tag names (e.g. fancy-button.html becomes <fancy-button>). Subfolders do not create separate namespaces.
  3. Keep companions co-located: Keep .css and script files paired with their corresponding .html template so bascik add copies all associated assets.

Semantic versioning

When publishing updates to a component package:

  • Patch (1.0.1): Bug fixes and styling improvements that do not change the component's public interface or tag names.
  • Minor (1.1.0): New components or backward-compatible props/slots additions.
  • Major (2.0.0): Breaking prop renames, slot changes, or tag name modifications.

Consumers tracking your package via bascik-lock.json can re-run bascik add <package> to pull in new versions cleanly, while locally modified files are protected from accidental overwrites.