npm - @knighted/css - Versions diffs - 1.0.0-alpha.0 - Mend

@knighted/css 1.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,117 @@
+# [`@knighted/css`](https://github.com/knightedcodemonkey/css)
+![CI](https://github.com/knightedcodemonkey/css/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/knightedcodemonkey/css/graph/badge.svg?token=q93Qqwvq6l)](https://codecov.io/gh/knightedcodemonkey/css)
+[![NPM version](https://img.shields.io/npm/v/@knighted/css.svg)](https://www.npmjs.com/package/@knighted/css)
+`@knighted/css` is a build-time helper that walks a JavaScript/TypeScript module graph, finds every CSS-like dependency (plain CSS, Sass/SCSS, Less, vanilla-extract), compiles them, and returns a single concatenated stylesheet string. It is designed to power zero-runtime styling workflows like Lit custom elements, server-side rendering, or pre-rendering pipelines where you need all CSS for a specific entry point without running a full bundler.
+## Features
+- Traverses module graphs using [`dependency-tree`](https://github.com/dependents/node-dependency-tree) to find transitive style imports.
+- Compiles `*.css`, `*.scss`, `*.sass`, `*.less`, and `*.css.ts` (vanilla-extract) files out of the box.
+- Optional post-processing via [`lightningcss`](https://github.com/parcel-bundler/lightningcss) for minification, prefixing, and media query optimizations.
+- Pluggable resolver/filter hooks for custom module resolution (e.g., Rspack/Vite/webpack aliases) or selective inclusion.
+- Peer-resolution helper for optional toolchains (`sass`, `less`, `@vanilla-extract/integration`) so consumers control their dependency graph.
+## Requirements
+- Node.js `>= 22.15.0`
+- npm `>= 10.9.0`
+- Install peer toolchains you intend to use (`sass`, `less`, `@vanilla-extract/integration`, `@vanilla-extract/recipes`, etc.).
+## Installation
+```bash
+npm install @knighted/css \
+  sass less \
+  @vanilla-extract/css @vanilla-extract/integration @vanilla-extract/recipes
+```
+Only install the peers you need—if your project never touches Less, you can skip `less`, etc.
+## Quick Start
+```ts
+// scripts/extract-styles.ts
+import { css } from '@knighted/css'
+const styles = await css('./src/components/app.ts', {
+  cwd: process.cwd(),
+  lightningcss: { minify: true },
+})
+console.log(styles)
+```
+Run it with `tsx`/`node` and you will see a fully inlined stylesheet for `app.ts` and every style import it references, regardless of depth.
+## API
+```ts
+type CssOptions = {
+  extensions?: string[] // customize file extensions to scan
+  cwd?: string // working directory (defaults to process.cwd())
+  filter?: (filePath: string) => boolean
+  lightningcss?: boolean | LightningTransformOptions
+  dependencyTree?: DependencyTreeOptions
+  resolver?: (
+    specifier: string,
+    ctx: { cwd: string },
+  ) => string | Promise<string | undefined>
+  peerResolver?: (name: string) => Promise<unknown> // for custom module loading
+}
+async function css(entry: string, options?: CssOptions): Promise<string>
+```
+Typical customizations:
+- **filter** – Skip certain paths (e.g., storybook-only styles) before compilation.
+- **resolver** – Resolve virtual specifiers the way your bundler does (the repo ships test fixtures for webpack, Vite, and Rspack).
+- **lightningcss** – Pass `true` for defaults or a config object for minification/autoprefixing.
+## Examples
+### Extract styles for Lit components
+```ts
+import { writeFile } from 'node:fs/promises'
+import { css } from '@knighted/css'
+const sheet = await css('./src/lit/my-widget.ts', {
+  lightningcss: { minify: true, targets: { chrome: 120 } },
+})
+await writeFile('./dist/my-widget.css', sheet)
+```
+### Inline CSS during SSR
+```ts
+import { renderToString } from 'react-dom/server'
+import { css } from '@knighted/css'
+export async function render(url: string) {
+  const styles = await css('./src/routes/root.tsx')
+  const html = renderToString(<App url={url} />)
+  return `<!doctype html><style>${styles}</style>${html}`
+}
+```
+## Scripts
+- `npm run build` – Produce CJS/ESM outputs via `@knighted/duel`.
+- `npm test` – Runs the Node test suite with `tsx` and reports coverage via `c8`.
+- `npm run lint` – Static analysis through `oxlint`.
+## Contributing
+1. Clone the repo and install dependencies with `npm install`.
+2. Run `npm test` to ensure fixtures compile across Sass/Less/vanilla-extract.
+3. Add/adjust fixtures in `fixtures/` when adding new language features to keep coverage high.
+4. Open a PR with a description of the change and tests.
+## License
+MIT © Knighted Code Monkey

package/dist/cjs/css.cjs ADDED Viewed

@@ -0,0 +1,197 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EXTENSIONS = void 0;
+exports.css = css;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const dependency_tree_1 = __importDefault(require("dependency-tree"));
+const lightningcss_1 = require("lightningcss");
+exports.DEFAULT_EXTENSIONS = ['.css', '.scss', '.sass', '.less', '.css.ts'];
+/**
+ * Extract and compile all CSS-like dependencies for a given module.
+ */
+async function css(entry, options = {}) {
+    const cwd = options.cwd ? node_path_1.default.resolve(options.cwd) : process.cwd();
+    const entryPath = await resolveEntry(entry, cwd, options.resolver);
+    const extensions = (options.extensions ?? exports.DEFAULT_EXTENSIONS).map(ext => ext.toLowerCase());
+    const files = collectStyleDependencies(entryPath, {
+        cwd,
+        extensions,
+        filter: options.filter,
+        dependencyTreeOptions: options.dependencyTree,
+    });
+    if (files.length === 0) {
+        return '';
+    }
+    const chunks = [];
+    for (const file of files) {
+        const chunk = await compileStyleModule(file, {
+            cwd,
+            peerResolver: options.peerResolver,
+        });
+        if (chunk) {
+            chunks.push(chunk);
+        }
+    }
+    let output = chunks.join('\n');
+    if (options.lightningcss) {
+        const lightningOptions = normalizeLightningOptions(options.lightningcss);
+        const { code } = (0, lightningcss_1.transform)({
+            ...lightningOptions,
+            filename: lightningOptions.filename ?? 'extracted.css',
+            code: Buffer.from(output),
+        });
+        output = code.toString();
+    }
+    return output;
+}
+async function resolveEntry(entry, cwd, resolver) {
+    if (typeof resolver === 'function') {
+        const resolved = await resolver(entry, { cwd });
+        if (resolved) {
+            return resolved;
+        }
+    }
+    if (node_path_1.default.isAbsolute(entry)) {
+        return entry;
+    }
+    return node_path_1.default.resolve(cwd, entry);
+}
+function collectStyleDependencies(entryPath, { cwd, extensions, filter, dependencyTreeOptions, }) {
+    const seen = new Set();
+    const order = [];
+    const shouldInclude = typeof filter === 'function'
+        ? filter
+        : (filePath) => !filePath.includes('node_modules');
+    const entryIsStyle = Boolean(matchExtension(entryPath, extensions));
+    let treeList = [];
+    if (!entryIsStyle) {
+        const dependencyConfig = {
+            ...dependencyTreeOptions,
+            filename: entryPath,
+            directory: cwd,
+            filter: shouldInclude,
+        };
+        treeList = dependency_tree_1.default.toList(dependencyConfig);
+    }
+    const candidates = entryIsStyle ? [entryPath] : [entryPath, ...treeList];
+    for (const candidate of candidates) {
+        const match = matchExtension(candidate, extensions);
+        if (!match || seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        order.push({ path: node_path_1.default.resolve(candidate), ext: match });
+    }
+    return order;
+}
+function matchExtension(filePath, extensions) {
+    const lower = filePath.toLowerCase();
+    return extensions.find(ext => lower.endsWith(ext));
+}
+async function compileStyleModule(file, { cwd, peerResolver }) {
+    switch (file.ext) {
+        case '.css':
+            return node_fs_1.promises.readFile(file.path, 'utf8');
+        case '.scss':
+        case '.sass':
+            return compileSass(file.path, file.ext === '.sass', peerResolver);
+        case '.less':
+            return compileLess(file.path, peerResolver);
+        case '.css.ts':
+            return compileVanillaExtract(file.path, cwd, peerResolver);
+        default:
+            return '';
+    }
+}
+async function compileSass(filePath, indented, peerResolver) {
+    const sassModule = await optionalPeer('sass', 'Sass', peerResolver);
+    const sass = sassModule;
+    const result = sass.compile(filePath, {
+        style: 'expanded',
+    });
+    return result.css;
+}
+async function compileLess(filePath, peerResolver) {
+    const mod = await optionalPeer('less', 'Less', peerResolver);
+    const less = unwrapModuleNamespace(mod);
+    const source = await node_fs_1.promises.readFile(filePath, 'utf8');
+    const result = await less.render(source, { filename: filePath });
+    return result.css;
+}
+async function compileVanillaExtract(filePath, cwd, peerResolver) {
+    const mod = await optionalPeer('@vanilla-extract/integration', 'Vanilla Extract', peerResolver);
+    const namespace = unwrapModuleNamespace(mod);
+    const compileFn = namespace.compile;
+    const transformPlugin = namespace.vanillaExtractTransformPlugin;
+    const processVanillaFile = namespace.processVanillaFile;
+    const getSourceFromVirtualCssFile = namespace.getSourceFromVirtualCssFile;
+    if (!compileFn ||
+        !getSourceFromVirtualCssFile ||
+        !transformPlugin ||
+        !processVanillaFile) {
+        throw new Error('@knighted/css: Unable to load "@vanilla-extract/integration". Please ensure the package exports compile helpers.');
+    }
+    const identOption = process.env.NODE_ENV === 'production' ? 'short' : 'debug';
+    const { source } = await compileFn({
+        filePath,
+        cwd,
+        identOption,
+        esbuildOptions: {
+            plugins: [transformPlugin({ identOption })],
+        },
+    });
+    const processedSource = await processVanillaFile({
+        source,
+        filePath,
+        identOption,
+        outputCss: true,
+    });
+    const imports = [];
+    const importRegex = /['"](?<id>[^'"]+\.vanilla\.css\?source=[^'"]+)['"]/gimu;
+    let match;
+    while ((match = importRegex.exec(processedSource)) !== null) {
+        const id = match.groups?.id ?? match[1];
+        if (!id)
+            continue;
+        const virtualFile = await getSourceFromVirtualCssFile(id);
+        if (virtualFile?.source) {
+            imports.push(virtualFile.source);
+        }
+    }
+    return imports.join('\n');
+}
+const defaultPeerLoader = name => import(name);
+async function optionalPeer(name, label, loader) {
+    const importer = loader ?? defaultPeerLoader;
+    try {
+        return (await importer(name));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            typeof error.code === 'string' &&
+            /MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND/.test(error.code)) {
+            throw new Error(`@knighted/css: Attempted to process ${label}, but "${name}" is not installed. Please add it to your project.`);
+        }
+        throw error;
+    }
+}
+function unwrapModuleNamespace(mod) {
+    if (typeof mod === 'object' &&
+        mod !== null &&
+        'default' in mod &&
+        mod.default) {
+        return mod.default;
+    }
+    return mod;
+}
+function normalizeLightningOptions(config) {
+    if (!config || config === true) {
+        return {};
+    }
+    return config;
+}

package/dist/cjs/css.d.cts ADDED Viewed

@@ -0,0 +1,22 @@
+import type { DependencyTreeOptions } from 'dependency-tree';
+import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
+export declare const DEFAULT_EXTENSIONS: string[];
+type LightningCssConfig = boolean | Partial<Omit<LightningTransformOptions<never>, 'code'>>;
+export type CssResolver = (specifier: string, ctx: {
+    cwd: string;
+}) => string | Promise<string | undefined>;
+type PeerLoader = (name: string) => Promise<unknown>;
+export interface CssOptions {
+    extensions?: string[];
+    cwd?: string;
+    filter?: (filePath: string) => boolean;
+    lightningcss?: LightningCssConfig;
+    dependencyTree?: Partial<Omit<DependencyTreeOptions, 'filename' | 'directory'>>;
+    resolver?: CssResolver;
+    peerResolver?: PeerLoader;
+}
+/**
+ * Extract and compile all CSS-like dependencies for a given module.
+ */
+export declare function css(entry: string, options?: CssOptions): Promise<string>;
+export {};

package/dist/css.d.ts ADDED Viewed

@@ -0,0 +1,22 @@
+import type { DependencyTreeOptions } from 'dependency-tree';
+import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
+export declare const DEFAULT_EXTENSIONS: string[];
+type LightningCssConfig = boolean | Partial<Omit<LightningTransformOptions<never>, 'code'>>;
+export type CssResolver = (specifier: string, ctx: {
+    cwd: string;
+}) => string | Promise<string | undefined>;
+type PeerLoader = (name: string) => Promise<unknown>;
+export interface CssOptions {
+    extensions?: string[];
+    cwd?: string;
+    filter?: (filePath: string) => boolean;
+    lightningcss?: LightningCssConfig;
+    dependencyTree?: Partial<Omit<DependencyTreeOptions, 'filename' | 'directory'>>;
+    resolver?: CssResolver;
+    peerResolver?: PeerLoader;
+}
+/**
+ * Extract and compile all CSS-like dependencies for a given module.
+ */
+export declare function css(entry: string, options?: CssOptions): Promise<string>;
+export {};

package/dist/css.js ADDED Viewed

@@ -0,0 +1,190 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import dependencyTree from 'dependency-tree';
+import { transform as lightningTransform, } from 'lightningcss';
+export const DEFAULT_EXTENSIONS = ['.css', '.scss', '.sass', '.less', '.css.ts'];
+/**
+ * Extract and compile all CSS-like dependencies for a given module.
+ */
+export async function css(entry, options = {}) {
+    const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+    const entryPath = await resolveEntry(entry, cwd, options.resolver);
+    const extensions = (options.extensions ?? DEFAULT_EXTENSIONS).map(ext => ext.toLowerCase());
+    const files = collectStyleDependencies(entryPath, {
+        cwd,
+        extensions,
+        filter: options.filter,
+        dependencyTreeOptions: options.dependencyTree,
+    });
+    if (files.length === 0) {
+        return '';
+    }
+    const chunks = [];
+    for (const file of files) {
+        const chunk = await compileStyleModule(file, {
+            cwd,
+            peerResolver: options.peerResolver,
+        });
+        if (chunk) {
+            chunks.push(chunk);
+        }
+    }
+    let output = chunks.join('\n');
+    if (options.lightningcss) {
+        const lightningOptions = normalizeLightningOptions(options.lightningcss);
+        const { code } = lightningTransform({
+            ...lightningOptions,
+            filename: lightningOptions.filename ?? 'extracted.css',
+            code: Buffer.from(output),
+        });
+        output = code.toString();
+    }
+    return output;
+}
+async function resolveEntry(entry, cwd, resolver) {
+    if (typeof resolver === 'function') {
+        const resolved = await resolver(entry, { cwd });
+        if (resolved) {
+            return resolved;
+        }
+    }
+    if (path.isAbsolute(entry)) {
+        return entry;
+    }
+    return path.resolve(cwd, entry);
+}
+function collectStyleDependencies(entryPath, { cwd, extensions, filter, dependencyTreeOptions, }) {
+    const seen = new Set();
+    const order = [];
+    const shouldInclude = typeof filter === 'function'
+        ? filter
+        : (filePath) => !filePath.includes('node_modules');
+    const entryIsStyle = Boolean(matchExtension(entryPath, extensions));
+    let treeList = [];
+    if (!entryIsStyle) {
+        const dependencyConfig = {
+            ...dependencyTreeOptions,
+            filename: entryPath,
+            directory: cwd,
+            filter: shouldInclude,
+        };
+        treeList = dependencyTree.toList(dependencyConfig);
+    }
+    const candidates = entryIsStyle ? [entryPath] : [entryPath, ...treeList];
+    for (const candidate of candidates) {
+        const match = matchExtension(candidate, extensions);
+        if (!match || seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        order.push({ path: path.resolve(candidate), ext: match });
+    }
+    return order;
+}
+function matchExtension(filePath, extensions) {
+    const lower = filePath.toLowerCase();
+    return extensions.find(ext => lower.endsWith(ext));
+}
+async function compileStyleModule(file, { cwd, peerResolver }) {
+    switch (file.ext) {
+        case '.css':
+            return fs.readFile(file.path, 'utf8');
+        case '.scss':
+        case '.sass':
+            return compileSass(file.path, file.ext === '.sass', peerResolver);
+        case '.less':
+            return compileLess(file.path, peerResolver);
+        case '.css.ts':
+            return compileVanillaExtract(file.path, cwd, peerResolver);
+        default:
+            return '';
+    }
+}
+async function compileSass(filePath, indented, peerResolver) {
+    const sassModule = await optionalPeer('sass', 'Sass', peerResolver);
+    const sass = sassModule;
+    const result = sass.compile(filePath, {
+        style: 'expanded',
+    });
+    return result.css;
+}
+async function compileLess(filePath, peerResolver) {
+    const mod = await optionalPeer('less', 'Less', peerResolver);
+    const less = unwrapModuleNamespace(mod);
+    const source = await fs.readFile(filePath, 'utf8');
+    const result = await less.render(source, { filename: filePath });
+    return result.css;
+}
+async function compileVanillaExtract(filePath, cwd, peerResolver) {
+    const mod = await optionalPeer('@vanilla-extract/integration', 'Vanilla Extract', peerResolver);
+    const namespace = unwrapModuleNamespace(mod);
+    const compileFn = namespace.compile;
+    const transformPlugin = namespace.vanillaExtractTransformPlugin;
+    const processVanillaFile = namespace.processVanillaFile;
+    const getSourceFromVirtualCssFile = namespace.getSourceFromVirtualCssFile;
+    if (!compileFn ||
+        !getSourceFromVirtualCssFile ||
+        !transformPlugin ||
+        !processVanillaFile) {
+        throw new Error('@knighted/css: Unable to load "@vanilla-extract/integration". Please ensure the package exports compile helpers.');
+    }
+    const identOption = process.env.NODE_ENV === 'production' ? 'short' : 'debug';
+    const { source } = await compileFn({
+        filePath,
+        cwd,
+        identOption,
+        esbuildOptions: {
+            plugins: [transformPlugin({ identOption })],
+        },
+    });
+    const processedSource = await processVanillaFile({
+        source,
+        filePath,
+        identOption,
+        outputCss: true,
+    });
+    const imports = [];
+    const importRegex = /['"](?<id>[^'"]+\.vanilla\.css\?source=[^'"]+)['"]/gimu;
+    let match;
+    while ((match = importRegex.exec(processedSource)) !== null) {
+        const id = match.groups?.id ?? match[1];
+        if (!id)
+            continue;
+        const virtualFile = await getSourceFromVirtualCssFile(id);
+        if (virtualFile?.source) {
+            imports.push(virtualFile.source);
+        }
+    }
+    return imports.join('\n');
+}
+const defaultPeerLoader = name => import(name);
+async function optionalPeer(name, label, loader) {
+    const importer = loader ?? defaultPeerLoader;
+    try {
+        return (await importer(name));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            typeof error.code === 'string' &&
+            /MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND/.test(error.code)) {
+            throw new Error(`@knighted/css: Attempted to process ${label}, but "${name}" is not installed. Please add it to your project.`);
+        }
+        throw error;
+    }
+}
+function unwrapModuleNamespace(mod) {
+    if (typeof mod === 'object' &&
+        mod !== null &&
+        'default' in mod &&
+        mod.default) {
+        return mod.default;
+    }
+    return mod;
+}
+function normalizeLightningOptions(config) {
+    if (!config || config === true) {
+        return {};
+    }
+    return config;
+}

package/package.json ADDED Viewed

@@ -0,0 +1,105 @@
+{
+  "name": "@knighted/css",
+  "version": "1.0.0-alpha.0",
+  "description": "A build-time utility that traverses JavaScript/TypeScript module dependency graphs to extract, compile, and optimize all imported CSS into a single, in-memory string.",
+  "type": "module",
+  "main": "./dist/css.js",
+  "types": "./dist/css.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/css.d.ts",
+      "import": "./dist/css.js",
+      "require": "./dist/cjs/css.cjs"
+    }
+  },
+  "engines": {
+    "node": ">= 22.15.0",
+    "npm": ">= 10.9.0"
+  },
+  "engineStrict": true,
+  "keywords": [
+    "css",
+    "extract-css",
+    "styles",
+    "dependency-graph",
+    "module-dependencies",
+    "lit",
+    "web-components",
+    "shadow-dom",
+    "sass",
+    "scss",
+    "less",
+    "vanilla-extract",
+    "lightningcss",
+    "build-time",
+    "static-analysis",
+    "css-in-js-zero-runtime"
+  ],
+  "scripts": {
+    "build": "duel",
+    "test": "c8 --reporter=text --reporter=html tsx --test test/**/*.test.ts",
+    "prettier": "prettier --write .",
+    "prettier:check": "prettier --check .",
+    "lint": "oxlint src test",
+    "prepack": "npm run build",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "dependency-tree": "^9.0.0",
+    "lightningcss": "^1.30.2"
+  },
+  "peerDependencies": {
+    "@vanilla-extract/integration": "^8.0.0",
+    "less": "^4.2.0",
+    "sass": "^1.80.0"
+  },
+  "peerDependenciesMeta": {
+    "@vanilla-extract/integration": {
+      "optional": true
+    },
+    "less": {
+      "optional": true
+    },
+    "sass": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@knighted/duel": "^2.1.6",
+    "@types/less": "^3.0.8",
+    "@vanilla-extract/css": "^1.15.2",
+    "@vanilla-extract/integration": "^8.0.6",
+    "@vanilla-extract/recipes": "^0.5.7",
+    "c8": "^10.1.2",
+    "husky": "^9.1.7",
+    "less": "^4.2.0",
+    "lint-staged": "^16.2.7",
+    "oxlint": "^0.4.1",
+    "prettier": "^3.7.4",
+    "sass": "^1.80.7",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "KCM <knightedcodemonkey@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knightedcodemonkey/css.git"
+  },
+  "bugs": {
+    "url": "https://github.com/knightedcodemonkey/css/issues"
+  },
+  "prettier": {
+    "arrowParens": "avoid",
+    "printWidth": 90,
+    "semi": false,
+    "singleQuote": true
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,mjs,cjs,cts,mts}": "oxlint",
+    "*.{js,jsx,ts,tsx,mjs,cjs,cts,mts,json,md,css,scss,html}": "prettier --check"
+  }
+}