esm-styles 0.3.12 → 0.4.0

package/README.md

@@ -181,6 +181,11 @@ export default {
     hover: '(hover: hover)',
     // ...whatever you want
   },
+
+  // Import aliases (optional) - replace long relative paths with short prefixes
+  aliases: {
+    '@': '.', // resolves relative to sourcePath
+  },
 }
 ```
 
@@ -451,6 +456,50 @@ The build process wraps floors in their respective layers and generates a main C
 
 Missing variables in one theme automatically inherit from the previous theme in the configuration.
 
+### Import Aliases
+
+Simplify imports in your style files by configuring path aliases:
+
+```js
+// esm-styles.config.js
+export default {
+  // ...
+  aliases: {
+    '@': '.',           // @ resolves to sourcePath
+    '@components': './components',
+  },
+}
+```
+
+Then use in your style files:
+
+```js
+// Before (relative paths)
+import $theme from '../../$theme.mjs'
+import { button } from '../components/button.styles.mjs'
+
+// After (with aliases)
+import $theme from '@/$theme.mjs'
+import { button } from '@components/button.styles.mjs'
+```
+
+Alias paths are resolved relative to the `sourcePath` directory. This feature uses esbuild internally for fast module resolution.
+
+#### IDE Support for Aliases
+
+To enable Cmd+click navigation and IntelliSense for aliased imports, create a `jsconfig.json` in your styles source directory with matching path mappings:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  }
+}
+```
+
 ## Additional documentation
 
 For humans: [doc/usage-guide.md](doc/usage-guide.md)

package/dist/lib/build.js

@@ -7,6 +7,37 @@ import fs from 'node:fs/promises';
 // import { inspect } from 'node:util'
 import _ from 'lodash';
 import * as esbuild from 'esbuild';
+/**
+ * Import a module with alias resolution using esbuild.
+ * Falls back to direct import when no aliases are configured.
+ */
+async function importWithAliases(filePath, aliases, sourcePath) {
+    // If no aliases configured, use direct import with cache-busting
+    if (!aliases || Object.keys(aliases).length === 0) {
+        const fileUrl = pathToFileUrl(filePath).href + `?update=${Date.now()}`;
+        return import(fileUrl);
+    }
+    // Resolve aliases relative to sourcePath
+    const resolvedAliases = {};
+    for (const [key, value] of Object.entries(aliases)) {
+        resolvedAliases[key] = path.resolve(sourcePath, value);
+    }
+    // Use esbuild to bundle with alias resolution
+    const result = await esbuild.build({
+        entryPoints: [filePath],
+        bundle: true,
+        write: false,
+        format: 'esm',
+        platform: 'node',
+        alias: resolvedAliases,
+        // Prevent esbuild from trying to resolve node_modules
+        packages: 'external',
+    });
+    // Import from data URL to avoid filesystem caching
+    const code = result.outputFiles[0].text;
+    const dataUrl = `data:text/javascript;base64,${Buffer.from(code).toString('base64')}`;
+    return import(dataUrl);
+}
 export async function build(configPath = 'esm-styles.config.js') {
     // --- Supporting module generation ---
     // Debug: log mergedSets and sets
@@ -23,6 +54,7 @@ export async function build(configPath = 'esm-styles.config.js') {
     const suffix = config.sourceFilesSuffix || '.styles.mjs';
     const floors = config.floors || [];
     const mainCssFile = config.mainCssFile || 'styles.css';
+    const aliases = config.aliases;
     // Helper function to generate CSS comment header
     const generateCssComment = (sourceName) => {
         const normalizedBasePath = (config.basePath || '.').replace(/^\.*\//, '');
@@ -38,8 +70,8 @@ export async function build(configPath = 'esm-styles.config.js') {
     if (config.globalVariables) {
         const inputFile = path.join(sourcePath, `${config.globalVariables}${suffix}`);
         const outputFile = path.join(outputPath, `global.css`);
-        const fileUrl = pathToFileUrl(inputFile).href + `?update=${Date.now()}`;
-        const varsObj = (await import(fileUrl)).default;
+        const varsObj = (await importWithAliases(inputFile, aliases, sourcePath))
+            .default;
         const cssVars = getCssVariables(varsObj);
         const rootSelector = config.globalRootSelector || ':root';
         const comment = generateCssComment(config.globalVariables);
@@ -57,8 +89,7 @@ export async function build(configPath = 'esm-styles.config.js') {
             for (const setName of sets) {
                 // Inheritance: merge with previous
                 const inputFile = path.join(sourcePath, `${setName}${suffix}`);
-                const fileUrl = pathToFileUrl(inputFile).href + `?update=${Date.now()}`;
-                const varsObj = _.merge({}, prevVarsObj, (await import(fileUrl)).default);
+                const varsObj = _.merge({}, prevVarsObj, (await importWithAliases(inputFile, aliases, sourcePath)).default);
                 prevVarsObj = varsObj;
                 mergedSets[setName] = _.cloneDeep(varsObj);
                 // For each selector config for this set
@@ -187,8 +218,8 @@ export async function build(configPath = 'esm-styles.config.js') {
         // Ensure the output directory exists
         await fs.mkdir(floorOutputDir, { recursive: true });
         const outputFile = path.join(floorOutputDir, `${source}.css`);
-        const fileUrl = pathToFileUrl(inputFile).href + `?update=${Date.now()}`;
-        const stylesObj = (await import(fileUrl)).default;
+        const stylesObj = (await importWithAliases(inputFile, aliases, sourcePath))
+            .default;
         const css = getCss(stylesObj, {
             ...mediaShorthands,
             globalRootSelector: config.globalRootSelector,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esm-styles",
-  "version": "0.3.12",
+  "version": "0.4.0",
   "description": "A library for working with ESM styles",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",