@jesscss/plugin-node-modules 2.0.0-alpha.6 → 2.0.0-alpha.8

package/README.md

@@ -1,74 +1,35 @@
 # @jesscss/plugin-node-modules
 
-Jess plugin for resolving and loading npm packages from `node_modules`.
-
-## Overview
-
-This plugin provides npm/node_modules resolution and loading capabilities for all Jess language plugins. It uses Node's module resolution algorithm (`require.resolve`) to find and load npm packages.
-
-## Usage
-
-```typescript
-import { Compiler } from '@jesscss/jess';
-import nodeModulesPlugin from '@jesscss/plugin-node-modules';
-
-const compiler = new Compiler({
-  compile: {
-    plugins: [
-      nodeModulesPlugin(),
-      // ... other plugins
-    ]
-  }
-});
-```
-
-## API
-
-### `resolvePackage(packageName: string): string | null`
-
-Resolve an npm package name to its absolute path.
-
-```typescript
-const plugin = new NodeModulesPlugin();
-const path = plugin.resolvePackage('less-plugin-clean-css');
-// Returns: '/path/to/node_modules/less-plugin-clean-css/index.js' or null
-```
-
-### `loadPackage(packageName: string): Promise<Record<string, any> | null>`
-
-Load an npm package module.
-
-```typescript
-const plugin = new NodeModulesPlugin();
-const module = await plugin.loadPackage('less-plugin-clean-css');
-// Returns: the module exports, or null if not found
-```
-
-### `tryResolvePackages(packageNames: string[]): Promise<{ name: string; module: Record<string, any> } | null>`
-
-Try to resolve a package name with multiple possible names. Returns the first successfully resolved package.
-
-```typescript
-const plugin = new NodeModulesPlugin();
-const result = await plugin.tryResolvePackages([
-  'clean-css',
-  'less-plugin-clean-css'
-]);
-// Returns: { name: 'less-plugin-clean-css', module: {...} } or null
-```
-
-## Integration with Other Plugins
-
-Other plugins (like `@jesscss/plugin-less-compat`) can use this plugin to resolve npm packages:
-
-```typescript
-// In jess-plugin-less-compat
-const nodeModulesPlugin = plugins.find(p => p.name === 'node-modules');
-if (nodeModulesPlugin instanceof NodeModulesPlugin) {
-  const module = await nodeModulesPlugin.loadPackage('less-plugin-clean-css');
-}
-```
-
-## Options
-
-- `enabled` (boolean, default: `true`): Whether to enable auto-resolution of npm packages.
+**Import resolver that loads npm packages from `node_modules` — a seed of the
+JavaScript-execution / CSS-in-JS story.**
+
+This plugin gives Jess's language plugins a way to resolve and load npm packages
+by name, using Node's module resolution (`require.resolve` /
+`createRequire`). Other plugins use it to pull in packages referenced from a
+stylesheet — for example [`@jesscss/plugin-less-compat`](../jess-plugin-less-compat)
+resolving a Less `@plugin "package-name"` off `node_modules`.
+
+## Why it exists — the convergence angle
+
+One of the four tools [Jess](https://github.com/jesscss/jess) aims to converge is
+**CSS-in-JS**: running real JavaScript inside your stylesheets (`@use` /
+`@plugin`) so styles can be dynamic without leaving CSS files. Reaching npm
+packages is a building block of that story. Paired with
+[`@jesscss/plugin-js`](../jess-plugin-js) (which executes the modules), it lets a
+stylesheet pull logic and data from the JS ecosystem.
+
+That convergence is **roadmap — being proven through the alpha, not claimed as
+done.** What ships here today is just the resolver seam; don't read it as a
+finished CSS-in-JS system.
+
+## Status
+
+**Alpha.** Part of Jess, the ground-up rewrite of Less.js (Jess *is* Less.js
+v5). The programmatic plugin/compiler API is **not yet stabilized** — the `jess`
+/ `lessc` CLIs are the public surface for the alpha. Watch the
+[docs site](https://jesscss.github.io/) for the API once it settles.
+
+- Project overview & positioning: <https://github.com/jesscss/jess#readme>
+- Docs: <https://jesscss.github.io/> (currently pre-alpha content)
+- Issues: <https://github.com/jesscss/jess/issues>
+- License: MIT

package/lib/index.js

@@ -107,5 +107,3 @@ const nodeModulesPlugin = ((opts) => {
 });
 //#endregion
 export { NodeModulesPlugin, nodeModulesPlugin as default };
-
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@jesscss/plugin-node-modules",
-  "version": "2.0.0-alpha.6",
+  "version": "2.0.0-alpha.8",
   "description": "Jess plugin for resolving and loading npm packages from node_modules",
   "main": "lib/index.cjs",
   "types": "lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
-      "source": "./src/index.ts",
       "import": "./lib/index.js",
       "require": "./lib/index.cjs"
     },
@@ -17,7 +16,7 @@
     "lib"
   ],
   "dependencies": {
-    "@jesscss/core": "2.0.0-alpha.6"
+    "@jesscss/core": "2.0.0-alpha.8"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -32,7 +31,7 @@
   "module": "lib/index.js",
   "scripts": {
     "build": "pnpm compile",
-    "compile": "tsdown --tsconfig tsconfig.build.json && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "compile": "tsdown --tsconfig tsconfig.build.json --no-dts && tsc -p tsconfig.build.json --emitDeclarationOnly",
     "dev": "tsdown --tsconfig tsconfig.build.json --watch",
     "lint:fix": "eslint --fix '**/*.{js,ts}'",
     "lint": "eslint '**/*.{js,ts}'"

package/lib/index.d.cts

@@ -1,64 +0,0 @@
-import { AbstractPlugin } from "@jesscss/core";
-
-//#region src/index.d.ts
-interface NodeModulesPluginOptions {
-  /**
-   * Whether to enable auto-resolution of npm packages.
-   * Default: true
-   */
-  enabled?: boolean;
-}
-/**
- * Plugin that provides npm/node_modules resolution and loading capabilities.
- *
- * This plugin implements the `import()` method to resolve and load npm packages
- * using Node's module resolution algorithm (require.resolve).
- *
- * It can be used by other plugins (like jess-plugin-less-compat) to load
- * npm packages when processing directives like `@plugin "package-name"`.
- */
-declare class NodeModulesPlugin extends AbstractPlugin {
-  opts: NodeModulesPluginOptions;
-  name: string;
-  private _require;
-  constructor(opts?: NodeModulesPluginOptions);
-  /**
-   * Resolve an npm package name to its absolute path.
-   * Uses Node's module resolution algorithm (same as require.resolve).
-   *
-   * @param packageName - The npm package name (e.g., "less-plugin-clean-css")
-   * @returns The absolute path to the package, or null if not found
-   */
-  resolvePackage(packageName: string): string | null;
-  /**
-   * Load an npm package module.
-   *
-   * @param packageName - The npm package name (e.g., "less-plugin-clean-css")
-   * @returns The loaded module, or null if not found
-   */
-  loadPackage(packageName: string): Promise<Record<string, any> | null>;
-  /**
-   * Try to resolve a package name with multiple possible names.
-   * Useful for plugins that want to try different variations
-   * (e.g., "clean-css" and "less-plugin-clean-css").
-   *
-   * @param packageNames - Array of package names to try in order
-   * @returns The first successfully resolved package, or null if none found
-   */
-  tryResolvePackages(packageNames: string[]): Promise<{
-    name: string;
-    module: Record<string, any>;
-  } | null>;
-  /**
-   * Import method for loading JavaScript modules from npm.
-   * This is called by the context when importing modules.
-   *
-   * @param absoluteFilePath - The absolute path to the module
-   * @returns The loaded module, or throws if this plugin can't handle it
-   */
-  import(absoluteFilePath: string): Promise<Record<string, any>>;
-}
-declare const nodeModulesPlugin: (opts?: NodeModulesPluginOptions) => NodeModulesPlugin;
-//#endregion
-export { NodeModulesPlugin, type NodeModulesPluginOptions, nodeModulesPlugin as default };
-//# sourceMappingURL=index.d.cts.map

package/lib/index.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;;UASU,wBAAA;;AALa;;;EAUrB,OAAA;AAAA;;;;;;;;;;cAcW,iBAAA,SAA0B,cAAA;EAKlB,IAAA,EAAM,wBAAA;EAJzB,IAAA;EAAA,QAEQ,QAAA;cAEW,IAAA,GAAM,wBAAA;EAAN;;;;;;;EAqCnB,cAAA,CAAe,WAAA;EAAA;;;;;;EA0BT,WAAA,CAAY,WAAA,WAAsB,OAAA,CAAQ,MAAA;EAyBE;;;;;;;;EAA5C,kBAAA,CAAmB,YAAA,aAAyB,OAAA;IAAU,IAAA;IAAc,MAAA,EAAQ,MAAA;EAAA;;;;;;;;EAiB5E,MAAA,CAAO,gBAAA,WAA2B,OAAA,CAAQ,MAAA;AAAA;AAAA,cAsB5C,iBAAA,GAAiB,IAAA,GAAY,wBAAA,KAAwB,iBAAA"}

package/lib/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import {\n  type Plugin,\n  type PluginInterface,\n  AbstractPlugin\n} from '@jesscss/core';\nimport { createRequire } from 'node:module';\nimport { fileURLToPath } from 'node:url';\nimport * as path from 'node:path';\n\ninterface NodeModulesPluginOptions {\n  /**\n   * Whether to enable auto-resolution of npm packages.\n   * Default: true\n   */\n  enabled?: boolean;\n}\n\nexport type { NodeModulesPluginOptions };\n\n/**\n * Plugin that provides npm/node_modules resolution and loading capabilities.\n *\n * This plugin implements the `import()` method to resolve and load npm packages\n * using Node's module resolution algorithm (require.resolve).\n *\n * It can be used by other plugins (like jess-plugin-less-compat) to load\n * npm packages when processing directives like `@plugin \"package-name\"`.\n */\nexport class NodeModulesPlugin extends AbstractPlugin {\n  name = 'node-modules';\n\n  private _require: NodeRequire;\n\n  constructor(public opts: NodeModulesPluginOptions = {}) {\n    super();\n\n    // Create a require function that can resolve modules\n    // Use createRequire to get a require function in ES module contexts\n    try {\n      // Try to use the current file's directory as the base for resolution\n      let currentDir: string;\n      if (typeof __filename !== 'undefined') {\n        currentDir = path.dirname(__filename);\n      } else {\n        // In ES module contexts, try to use import.meta.url\n        // This will only work if the module system supports it\n        try {\n          const url = import.meta.url;\n          currentDir = path.dirname(fileURLToPath(url));\n        } catch {\n          // Fallback to process.cwd()\n          currentDir = process.cwd();\n        }\n      }\n      this._require = createRequire(currentDir + '/');\n    } catch {\n      // Fallback to global require if available\n      this._require = typeof require !== 'undefined'\n        ? require\n        : createRequire(process.cwd() + '/');\n    }\n  }\n\n  /**\n   * Resolve an npm package name to its absolute path.\n   * Uses Node's module resolution algorithm (same as require.resolve).\n   *\n   * @param packageName - The npm package name (e.g., \"less-plugin-clean-css\")\n   * @returns The absolute path to the package, or null if not found\n   */\n  resolvePackage(packageName: string): string | null {\n    if (this.opts.enabled === false) {\n      return null;\n    }\n\n    try {\n      // Use require.resolve to find the package\n      // This will search node_modules using Node's resolution algorithm\n      const resolved = this._require.resolve(packageName);\n      return resolved;\n    } catch (e: any) {\n      // MODULE_NOT_FOUND is expected when package doesn't exist\n      if (e.code === 'MODULE_NOT_FOUND') {\n        return null;\n      }\n      // Re-throw other errors\n      throw e;\n    }\n  }\n\n  /**\n   * Load an npm package module.\n   *\n   * @param packageName - The npm package name (e.g., \"less-plugin-clean-css\")\n   * @returns The loaded module, or null if not found\n   */\n  async loadPackage(packageName: string): Promise<Record<string, any> | null> {\n    const resolvedPath = this.resolvePackage(packageName);\n    if (!resolvedPath) {\n      return null;\n    }\n\n    try {\n      // Load the module using require\n\n      const module = this._require(resolvedPath) as Record<string, unknown>;\n      return module || null;\n    } catch {\n      // If loading fails, return null\n      return null;\n    }\n  }\n\n  /**\n   * Try to resolve a package name with multiple possible names.\n   * Useful for plugins that want to try different variations\n   * (e.g., \"clean-css\" and \"less-plugin-clean-css\").\n   *\n   * @param packageNames - Array of package names to try in order\n   * @returns The first successfully resolved package, or null if none found\n   */\n  async tryResolvePackages(packageNames: string[]): Promise<{ name: string; module: Record<string, any> } | null> {\n    for (const name of packageNames) {\n      const module = await this.loadPackage(name);\n      if (module !== null) {\n        return { name, module };\n      }\n    }\n    return null;\n  }\n\n  /**\n   * Import method for loading JavaScript modules from npm.\n   * This is called by the context when importing modules.\n   *\n   * @param absoluteFilePath - The absolute path to the module\n   * @returns The loaded module, or throws if this plugin can't handle it\n   */\n  async import(absoluteFilePath: string): Promise<Record<string, any>> {\n    if (this.opts.enabled === false) {\n      throw new Error(`Plugin \"${this.name}\" cannot import \"${absoluteFilePath}\" (disabled)`);\n    }\n\n    // Check if this looks like a node_modules path\n    // We can't directly resolve from absolute paths, but we can try to require it\n    if (absoluteFilePath.includes('node_modules')) {\n      try {\n        const module = this._require(absoluteFilePath) as Record<string, unknown>;\n        return module;\n      } catch (e: unknown) {\n        const message = e instanceof Error ? e.message : String(e);\n        throw new Error(`Failed to import \"${absoluteFilePath}\": ${message}`);\n      }\n    }\n\n    // For non-node_modules paths, throw to let other plugins handle it\n    throw new Error(`Plugin \"${this.name}\" cannot import \"${absoluteFilePath}\" (not a node_modules path)`);\n  }\n}\n\nconst nodeModulesPlugin = ((opts?: NodeModulesPluginOptions) => {\n  return new NodeModulesPlugin(opts);\n}) satisfies Plugin;\n\nexport default nodeModulesPlugin;\n"],"mappings":";;;;;;;;;;;;;;;;;AA4BA,IAAa,oBAAb,cAAuC,eAAe;CACpD,OAAO;CAEP;CAEA,YAAY,OAAwC,EAAE,EAAE;AACtD,SAAO;AADU,OAAA,OAAA;AAKjB,MAAI;GAEF,IAAI;AACJ,OAAI,OAAO,eAAe,YACxB,cAAa,KAAK,QAAQ,WAAW;OAIrC,KAAI;IACF,MAAM,MAAM,OAAO,KAAK;AACxB,iBAAa,KAAK,QAAQ,cAAc,IAAI,CAAC;WACvC;AAEN,iBAAa,QAAQ,KAAK;;AAG9B,QAAK,WAAW,cAAc,aAAa,IAAI;UACzC;AAEN,QAAK,WAAW,OAAA,cAAmB,cAAA,YAE/B,cAAc,QAAQ,KAAK,GAAG,IAAI;;;;;;;;;;CAW1C,eAAe,aAAoC;AACjD,MAAI,KAAK,KAAK,YAAY,MACxB,QAAO;AAGT,MAAI;AAIF,UADiB,KAAK,SAAS,QAAQ,YAAY;WAE5C,GAAQ;AAEf,OAAI,EAAE,SAAS,mBACb,QAAO;AAGT,SAAM;;;;;;;;;CAUV,MAAM,YAAY,aAA0D;EAC1E,MAAM,eAAe,KAAK,eAAe,YAAY;AACrD,MAAI,CAAC,aACH,QAAO;AAGT,MAAI;AAIF,UADe,KAAK,SAAS,aAAa,IACzB;UACX;AAEN,UAAO;;;;;;;;;;;CAYX,MAAM,mBAAmB,cAAuF;AAC9G,OAAK,MAAM,QAAQ,cAAc;GAC/B,MAAM,SAAS,MAAM,KAAK,YAAY,KAAK;AAC3C,OAAI,WAAW,KACb,QAAO;IAAE;IAAM;IAAQ;;AAG3B,SAAO;;;;;;;;;CAUT,MAAM,OAAO,kBAAwD;AACnE,MAAI,KAAK,KAAK,YAAY,MACxB,OAAM,IAAI,MAAM,WAAW,KAAK,KAAK,mBAAmB,iBAAiB,cAAc;AAKzF,MAAI,iBAAiB,SAAS,eAAe,CAC3C,KAAI;AAEF,UADe,KAAK,SAAS,iBAAiB;WAEvC,GAAY;GACnB,MAAM,UAAU,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE;AAC1D,SAAM,IAAI,MAAM,qBAAqB,iBAAiB,KAAK,UAAU;;AAKzE,QAAM,IAAI,MAAM,WAAW,KAAK,KAAK,mBAAmB,iBAAiB,6BAA6B;;;AAI1G,MAAM,sBAAsB,SAAoC;AAC9D,QAAO,IAAI,kBAAkB,KAAK"}