Installation

Package manager

npm

npm install @aejkatappaja/phantom-ui

pnpm

pnpm add @aejkatappaja/phantom-ui

yarn

yarn add @aejkatappaja/phantom-ui

bun

bun add @aejkatappaja/phantom-ui

Optionally, run npx @aejkatappaja/phantom-ui init once: it detects your framework (React, Solid, Qwik) and generates a TypeScript declaration file in your src/ directory. Vue, Svelte, and Angular need no extra setup. Nothing runs on install: the command is always explicit.

CDN

No build step needed. Drop in a script tag:

<script src="https://cdn.jsdelivr.net/npm/@aejkatappaja/phantom-ui/dist/phantom-ui.cdn.js"></script>

This bundles Lit and the component into a single file, ~34kb minified and ~11.5kb gzipped. The <phantom-ui> tag is available immediately.

Vendoring a single file

If a registry install is not an option, or you would rather keep a copy inside your repo, use the standalone ES module. It is the same code as the CDN build with Lit bundled in, but as an ES module you can import:

import "@aejkatappaja/phantom-ui/standalone";

Or copy dist/phantom-ui.standalone.js into your project and import it by path. The element registers itself on import, so <phantom-ui> works from that point on with no package manager involved at runtime.

If you cannot reach a registry at all, copy two files instead and import by path:

phantom-ui.standalone.js      # the component, unminified so a review can read it
phantom-ui.standalone.min.js  # the same code, minified
phantom-ui.standalone.d.ts    # its types, no imports of any kind

Take the first and the third: TypeScript pairs a declaration to a module by exact filename, so those two names belong together.

import "./phantom-ui.standalone.js";
import type { PhantomUi } from "./phantom-ui.standalone.js";

Nothing else is needed. The declarations reference no external module, so a project with no node_modules still type-checks under strict with skipLibCheck: false. The declared class extends HTMLElement rather than LitElement, a narrower view of the same object, so updateComplete is declared explicitly and the rest of the public API is unchanged.

The library is MIT, so vendoring is fine. Record the version you copied next to the file: a vendored copy receives no updates, and it is easy to spend time on a bug that is already fixed upstream.

What gets installed

node_modules/@aejkatappaja/phantom-ui/
  dist/
    phantom-ui.js             # ES module (Lit as external)
    phantom-ui.cdn.js         # IIFE standalone (Lit included)
    phantom-ui.standalone.js  # ES module standalone (Lit included)
    phantom-ui.standalone.dev.js # the same, unminified
    phantom-ui.standalone.d.ts # its declarations, no imports
    phantom-ui.d.ts           # TypeScript declarations
  custom-elements.json        # IDE/Storybook manifest
  package.json
  LICENSE
  README.md