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

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,80 @@ 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. Recommended DX: import your component as usual, and import the CSS separately via the query import.
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.[jt]sx?$/,
+        resourceQuery: /knighted-css/,
+        use: [
+          {
+            loader: '@knighted/css/loader',
+            options: {
+              lightningcss: { minify: true }, // all css() options supported
+            },
+          },
+        ],
+      },
+    ],
+  },
+}
+```
+
+```ts
+// lit wrapper
+import { LitElement, html, unsafeCSS } from 'lit'
+import { Button } from './button.tsx'
+import { knightedCss as reactStyles } from './button.tsx?knighted-css'
+
+export class ButtonWrapper extends LitElement {
+  static styles = [unsafeCSS(reactStyles)]
+  render() {
+    return html`<${Button} />`
+  }
+}
+
+// Prefer import aliasing when you need a different local name:
+// import { knightedCss as cardCss } from './button.tsx?knighted-css'
+```
+
+The loader appends `export const knightedCss = "/* compiled css */"` to the module when imported with `?knighted-css`. Keep your main module import separate to preserve its typing; use the query import only for the CSS string.
+
+### Custom resolver (enhanced-resolve example)
+
+If your project uses aliases or nonstandard resolution, plug in a custom resolver. Here’s how to use [`enhanced-resolve`](https://github.com/webpack/enhanced-resolve):
+
+```ts
+import { ResolverFactory } from 'enhanced-resolve'
+import { css } from '@knighted/css'
+
+const resolver = ResolverFactory.createResolver({
+  extensions: ['.ts', '.tsx', '.js'],
+  mainFiles: ['index'],
+})
+
+async function resolveWithEnhanced(id: string, cwd: string): Promise<string | undefined> {
+  return new Promise((resolve, reject) => {
+    resolver.resolve({}, cwd, id, {}, (err, result) => {
+      if (err) return reject(err)
+      resolve(result ?? undefined)
+    })
+  })
+}
+
+const styles = await css('./src/routes/page.tsx', {
+  resolver: (specifier, { cwd }) => resolveWithEnhanced(specifier, cwd),
+})
+```
+
+This keeps `@knighted/css` resolution in sync with your bundler’s alias/extension rules.
+
 ## 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

@@ -1,4 +1,4 @@
-import type { DependencyTreeOptions } from 'dependency-tree';
+import type { Options as DependencyTreeOpts } from 'dependency-tree';
 import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
 export declare const DEFAULT_EXTENSIONS: string[];
 type LightningCssConfig = boolean | Partial<Omit<LightningTransformOptions<never>, 'code'>>;
@@ -11,12 +11,17 @@ export interface CssOptions {
     cwd?: string;
     filter?: (filePath: string) => boolean;
     lightningcss?: LightningCssConfig;
-    dependencyTree?: Partial<Omit<DependencyTreeOptions, 'filename' | 'directory'>>;
+    dependencyTree?: Partial<Omit<DependencyTreeOpts, 'filename' | 'directory'>>;
     resolver?: CssResolver;
     peerResolver?: PeerLoader;
 }
 /**
  * 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,25 @@
+"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 cssOptions = rawOptions;
+    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 ${DEFAULT_EXPORT_NAME} = ${JSON.stringify(css)};\n`;
+    const isStyleModule = this.resourcePath.endsWith('.css.ts');
+    const output = isStyleModule
+        ? `${injection}export default {};\n`
+        : `${input}${injection}`;
+    return output;
+};
+exports.default = loader;

package/dist/cjs/loader.d.cts

@@ -0,0 +1,6 @@
+import type { LoaderDefinitionFunction } from 'webpack';
+import { type CssOptions } from './css.cjs';
+export interface KnightedCssLoaderOptions extends CssOptions {
+}
+declare const loader: LoaderDefinitionFunction<KnightedCssLoaderOptions>;
+export default loader;

package/dist/css.d.ts

@@ -1,4 +1,4 @@
-import type { DependencyTreeOptions } from 'dependency-tree';
+import type { Options as DependencyTreeOpts } from 'dependency-tree';
 import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
 export declare const DEFAULT_EXTENSIONS: string[];
 type LightningCssConfig = boolean | Partial<Omit<LightningTransformOptions<never>, 'code'>>;
@@ -11,12 +11,17 @@ export interface CssOptions {
     cwd?: string;
     filter?: (filePath: string) => boolean;
     lightningcss?: LightningCssConfig;
-    dependencyTree?: Partial<Omit<DependencyTreeOptions, 'filename' | 'directory'>>;
+    dependencyTree?: Partial<Omit<DependencyTreeOpts, 'filename' | 'directory'>>;
     resolver?: CssResolver;
     peerResolver?: PeerLoader;
 }
 /**
  * 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/index.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="./loader-queries.d.ts" />
+
+export * from '../css.js'
+export { default } from '../css.js'

package/dist/loader-queries.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Ambient declaration for loader query imports like "./file.js?knighted-css".
+ * The loader appends a named export `knightedCss` containing the compiled CSS.
+ */
+declare module '*?knighted-css*' {
+  export const knightedCss: string
+}

package/dist/loader.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="./loader-queries.d.ts" />
+
+export * from '../loader.js'
+export { default } from '../loader.js'

package/dist/loader.js

@@ -0,0 +1,23 @@
+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 cssOptions = rawOptions;
+    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 ${DEFAULT_EXPORT_NAME} = ${JSON.stringify(css)};\n`;
+    const isStyleModule = this.resourcePath.endsWith('.css.ts');
+    const output = isStyleModule
+        ? `${injection}export default {};\n`
+        : `${input}${injection}`;
+    return output;
+};
+export default loader;

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "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",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/css.d.ts",
+      "types": "./dist/index.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,16 @@
   ],
   "scripts": {
     "build": "duel",
-    "test": "c8 --reporter=text --reporter=html tsx --test test/**/*.test.ts",
+    "postbuild": "cp src/types/*.d.ts dist/",
+    "check-types": "tsc --noEmit",
+    "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov --include \"src/**/*.ts\" tsx --test test/**/*.test.ts",
+    "build:fixture": "npx rspack --config test/fixtures/loader-rspack/rspack.config.js",
+    "preview:fixture": "npm run build:fixture && npx http-server test/fixtures/loader-rspack -p 4173",
+    "prebuild:fixture:playwright": "npm run build",
+    "build:fixture:playwright": "npx rspack --config test/fixtures/playwright/rspack.config.js",
+    "serve:fixture:playwright": "npx http-server test/fixtures/playwright/dist -p 4174",
+    "preview:fixture:playwright": "npm run build:fixture:playwright && npx http-server test/fixtures/playwright -p 4174",
+    "test:e2e": "npx playwright test",
     "prettier": "prettier --write .",
     "prettier:check": "prettier --check .",
     "lint": "oxlint src test",
@@ -45,7 +59,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "dependency-tree": "^9.0.0",
+    "dependency-tree": "^11.2.0",
     "lightningcss": "^1.30.2"
   },
   "peerDependencies": {
@@ -66,11 +80,16 @@
   },
   "devDependencies": {
     "@knighted/duel": "^2.1.6",
+    "@playwright/test": "^1.48.2",
+    "@rspack/cli": "^1.0.0",
+    "@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",
     "c8": "^10.1.2",
+    "http-server": "^14.1.1",
     "husky": "^9.1.7",
     "less": "^4.2.0",
     "lint-staged": "^16.2.7",