@knighted/css 1.0.0-alpha.0 → 1.0.0-alpha.1

package/README.md

@@ -4,7 +4,7 @@
 [![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.
+`@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 for workflows where you want fully materialized styles ahead of time—feeding Lit components, server-rendered routes, static site builds, or any pipeline that needs all CSS for a specific entry point without running a full bundler.
 
 ## Features
 
@@ -23,12 +23,10 @@
 ## Installation
 
 ```bash
-npm install @knighted/css \
-  sass less \
-  @vanilla-extract/css @vanilla-extract/integration @vanilla-extract/recipes
+npm install @knighted/css
 ```
 
-Only install the peers you need—if your project never touches Less, you can skip `less`, etc.
+Install the peers your project is using, for example `less`, or `sass`, etc.
 
 ## Quick Start
 
@@ -73,17 +71,18 @@ Typical customizations:
 
 ## Examples
 
-### Extract styles for Lit components
+### Generate standalone stylesheets
 
 ```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 } },
+// Build-time script that gathers all CSS imported by a React route
+const sheet = await css('./src/routes/marketing-page.tsx', {
+  lightningcss: { minify: true, targets: { chrome: 120, safari: 17 } },
 })
 
-await writeFile('./dist/my-widget.css', sheet)
+await writeFile('./dist/marketing-page.css', sheet)
 ```
 
 ### Inline CSS during SSR
@@ -99,6 +98,52 @@ export async function render(url: string) {
 }
 ```
 
+### Bundler loader (`?knighted-css` query)
+
+When using Webpack/Rspack, add the provided loader so importing a module with a specific query also returns the compiled stylesheet:
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.[jt]sx?$/,
+        resourceQuery: /knighted-css/,
+        use: [
+          {
+            loader: '@knighted/css/loader',
+            options: {
+              exportName: 'reactStyles', // optional (default: "knightedCss")
+              lightningcss: { minify: true }, // all css() options supported
+            },
+          },
+        ],
+      },
+    ],
+  },
+}
+```
+
+```ts
+// lit wrapper
+import { LitElement, html, unsafeCSS } from 'lit'
+import { Button, reactStyles } from './button.tsx?knighted-css'
+
+export class ButtonWrapper extends LitElement {
+  static styles = [unsafeCSS(reactStyles)]
+  render() {
+    return html`<${Button} />`
+  }
+}
+
+// per-import override:
+// import { Button, cardCss } from './button.tsx?knighted-css&exportName=cardCss'
+// (exportName in the query wins over the loader option)
+```
+
+The loader appends `export const reactStyles = "/* compiled css */"` to the module, so you can wire it directly into Lit’s `static styles` or any other runtime.
+
 ## Scripts
 
 - `npm run build` – Produce CJS/ESM outputs via `@knighted/duel`.

package/dist/cjs/css.cjs

@@ -5,15 +5,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_EXTENSIONS = void 0;
 exports.css = css;
+exports.cssWithMeta = cssWithMeta;
 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 { css: output } = await cssWithMeta(entry, options);
+    return output;
+}
+async function cssWithMeta(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());
@@ -24,7 +26,7 @@ async function css(entry, options = {}) {
         dependencyTreeOptions: options.dependencyTree,
     });
     if (files.length === 0) {
-        return '';
+        return { css: '', files: [] };
     }
     const chunks = [];
     for (const file of files) {
@@ -46,7 +48,7 @@ async function css(entry, options = {}) {
         });
         output = code.toString();
     }
-    return output;
+    return { css: output, files: files.map(file => file.path) };
 }
 async function resolveEntry(entry, cwd, resolver) {
     if (typeof resolver === 'function') {

package/dist/cjs/css.d.cts

@@ -18,5 +18,10 @@ export interface CssOptions {
 /**
  * Extract and compile all CSS-like dependencies for a given module.
  */
+export interface CssResult {
+    css: string;
+    files: string[];
+}
 export declare function css(entry: string, options?: CssOptions): Promise<string>;
+export declare function cssWithMeta(entry: string, options?: CssOptions): Promise<CssResult>;
 export {};

package/dist/cjs/loader.cjs

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const css_js_1 = require("./css.cjs");
+const DEFAULT_EXPORT_NAME = 'knightedCss';
+const loader = async function loader(source) {
+    const rawOptions = (typeof this.getOptions === 'function' ? this.getOptions() : {});
+    const queryParams = typeof this.resourceQuery === 'string' && this.resourceQuery.startsWith('?')
+        ? new URLSearchParams(this.resourceQuery.slice(1))
+        : undefined;
+    const queryExportName = queryParams?.get('exportName')?.trim();
+    const isValidIdentifier = typeof queryExportName === 'string' &&
+        /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(queryExportName);
+    const { exportName = DEFAULT_EXPORT_NAME, ...cssOptions } = rawOptions;
+    const resolvedExportName = isValidIdentifier ? queryExportName : exportName;
+    const normalizedOptions = {
+        ...cssOptions,
+        cwd: cssOptions.cwd ?? this.rootContext ?? process.cwd(),
+    };
+    const { css, files } = await (0, css_js_1.cssWithMeta)(this.resourcePath, normalizedOptions);
+    const uniqueFiles = new Set([this.resourcePath, ...files]);
+    for (const file of uniqueFiles) {
+        this.addDependency(file);
+    }
+    const input = typeof source === 'string' ? source : source.toString('utf8');
+    const injection = `\n\nexport const ${resolvedExportName} = ${JSON.stringify(css)};\n`;
+    const output = `${input}${injection}`;
+    return output;
+};
+exports.default = loader;

package/dist/cjs/loader.d.cts

@@ -0,0 +1,11 @@
+import type { LoaderDefinitionFunction } from 'webpack';
+import { type CssOptions } from './css.cjs';
+export interface KnightedCssLoaderOptions extends CssOptions {
+    /**
+     * Named export that will contain the compiled CSS string.
+     * Defaults to "knightedCss".
+     */
+    exportName?: string;
+}
+declare const loader: LoaderDefinitionFunction<KnightedCssLoaderOptions>;
+export default loader;

package/dist/css.d.ts

@@ -18,5 +18,10 @@ export interface CssOptions {
 /**
  * Extract and compile all CSS-like dependencies for a given module.
  */
+export interface CssResult {
+    css: string;
+    files: string[];
+}
 export declare function css(entry: string, options?: CssOptions): Promise<string>;
+export declare function cssWithMeta(entry: string, options?: CssOptions): Promise<CssResult>;
 export {};

package/dist/css.js

@@ -3,10 +3,11 @@ 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 { css: output } = await cssWithMeta(entry, options);
+    return output;
+}
+export async function cssWithMeta(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());
@@ -17,7 +18,7 @@ export async function css(entry, options = {}) {
         dependencyTreeOptions: options.dependencyTree,
     });
     if (files.length === 0) {
-        return '';
+        return { css: '', files: [] };
     }
     const chunks = [];
     for (const file of files) {
@@ -39,7 +40,7 @@ export async function css(entry, options = {}) {
         });
         output = code.toString();
     }
-    return output;
+    return { css: output, files: files.map(file => file.path) };
 }
 async function resolveEntry(entry, cwd, resolver) {
     if (typeof resolver === 'function') {

package/dist/loader.d.ts

@@ -0,0 +1,11 @@
+import type { LoaderDefinitionFunction } from 'webpack';
+import { type CssOptions } from './css.js';
+export interface KnightedCssLoaderOptions extends CssOptions {
+    /**
+     * Named export that will contain the compiled CSS string.
+     * Defaults to "knightedCss".
+     */
+    exportName?: string;
+}
+declare const loader: LoaderDefinitionFunction<KnightedCssLoaderOptions>;
+export default loader;

package/dist/loader.js

@@ -0,0 +1,27 @@
+import { cssWithMeta } from './css.js';
+const DEFAULT_EXPORT_NAME = 'knightedCss';
+const loader = async function loader(source) {
+    const rawOptions = (typeof this.getOptions === 'function' ? this.getOptions() : {});
+    const queryParams = typeof this.resourceQuery === 'string' && this.resourceQuery.startsWith('?')
+        ? new URLSearchParams(this.resourceQuery.slice(1))
+        : undefined;
+    const queryExportName = queryParams?.get('exportName')?.trim();
+    const isValidIdentifier = typeof queryExportName === 'string' &&
+        /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(queryExportName);
+    const { exportName = DEFAULT_EXPORT_NAME, ...cssOptions } = rawOptions;
+    const resolvedExportName = isValidIdentifier ? queryExportName : exportName;
+    const normalizedOptions = {
+        ...cssOptions,
+        cwd: cssOptions.cwd ?? this.rootContext ?? process.cwd(),
+    };
+    const { css, files } = await cssWithMeta(this.resourcePath, normalizedOptions);
+    const uniqueFiles = new Set([this.resourcePath, ...files]);
+    for (const file of uniqueFiles) {
+        this.addDependency(file);
+    }
+    const input = typeof source === 'string' ? source : source.toString('utf8');
+    const injection = `\n\nexport const ${resolvedExportName} = ${JSON.stringify(css)};\n`;
+    const output = `${input}${injection}`;
+    return output;
+};
+export default loader;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.1",
   "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",
@@ -10,6 +10,11 @@
       "types": "./dist/css.d.ts",
       "import": "./dist/css.js",
       "require": "./dist/cjs/css.cjs"
+    },
+    "./loader": {
+      "types": "./dist/loader.d.ts",
+      "import": "./dist/loader.js",
+      "require": "./dist/cjs/loader.cjs"
     }
   },
   "engines": {
@@ -37,7 +42,8 @@
   ],
   "scripts": {
     "build": "duel",
-    "test": "c8 --reporter=text --reporter=html tsx --test test/**/*.test.ts",
+    "check-types": "tsc --noEmit",
+    "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov --include \"src/**/*.ts\" tsx --test test/**/*.test.ts",
     "prettier": "prettier --write .",
     "prettier:check": "prettier --check .",
     "lint": "oxlint src test",
@@ -66,7 +72,9 @@
   },
   "devDependencies": {
     "@knighted/duel": "^2.1.6",
+    "@rspack/core": "^1.0.0",
     "@types/less": "^3.0.8",
+    "@types/webpack": "^5.28.5",
     "@vanilla-extract/css": "^1.15.2",
     "@vanilla-extract/integration": "^8.0.6",
     "@vanilla-extract/recipes": "^0.5.7",