@visulima/rollup-plugin-css 1.0.0-alpha.1 → 1.0.0-alpha.11

package/README.md

@@ -7,7 +7,7 @@ A comprehensive CSS processing plugin for [Packem](https://github.com/visulima/p
 ### 🎨 CSS Preprocessors
 
 - **PostCSS** - Modern CSS transformations with plugin ecosystem
-- **Sass/SCSS** - Popular CSS extension language  
+- **Sass/SCSS** - Popular CSS extension language
 - **Less** - Dynamic stylesheet language
 - **Stylus** - Expressive, dynamic, robust CSS
 - **Tailwind CSS v4** - Latest Tailwind CSS with PostCSS integration
@@ -22,9 +22,10 @@ A comprehensive CSS processing plugin for [Packem](https://github.com/visulima/p
 
 ### 📦 Integration Modes
 
-- **Inject** - Embed CSS in JavaScript and inject at runtime
+- **Inject** - Embed CSS in JavaScript and inject at runtime (with customizable package and method)
 - **Extract** - Extract CSS to separate `.css` files
 - **Emit** - Pass processed CSS through the build pipeline
+- **Inline** - Embed CSS as strings in JavaScript modules
 
 ### 🔤 TypeScript Support
 
@@ -91,21 +92,21 @@ The `@visulima/rollup-plugin-css` provides comprehensive CSS processing capabili
 import { rollupCssPlugin } from "@visulima/rollup-plugin-css";
 
 export default {
-  plugins: [
-    rollupCssPlugin({
-      // Extract CSS to separate files
-      mode: "extract",
-      
-      // Enable CSS modules for .module.css files
-      autoModules: /\.module\./,
-      
-      // Enable source maps
-      sourceMap: true,
-      
-      // CSS minification
-      minifier: "cssnano",
-    })
-  ]
+    plugins: [
+        rollupCssPlugin({
+            // Extract CSS to separate files
+            mode: "extract",
+
+            // Enable CSS modules for .module.css files
+            autoModules: /\.module\./,
+
+            // Enable source maps
+            sourceMap: true,
+
+            // CSS minification
+            minifier: "cssnano",
+        }),
+    ],
 };
 ```
 
@@ -115,36 +116,33 @@ export default {
 import { rollupCssPlugin } from "@visulima/rollup-plugin-css";
 
 export default {
-  plugins: [
-    rollupCssPlugin({
-      // File extensions to process
-      extensions: [".css", ".scss", ".sass", ".less", ".styl"],
-      
-      // CSS Modules configuration
-      autoModules: true,
-      namedExports: true,
-      
-      // PostCSS configuration
-      postcss: {
-        plugins: [
-          require("autoprefixer"),
-          require("tailwindcss"),
-        ],
-        modules: {
-          generateScopedName: "[name]__[local]___[hash:base64:5]",
-        },
-      },
-      
-      // Sass configuration
-      sass: {
-        includePaths: ["node_modules"],
-        outputStyle: "compressed",
-      },
-      
-      // Minification
-      minifier: "lightningcss",
-    })
-  ]
+    plugins: [
+        rollupCssPlugin({
+            // File extensions to process
+            extensions: [".css", ".scss", ".sass", ".less", ".styl"],
+
+            // CSS Modules configuration
+            autoModules: true,
+            namedExports: true,
+
+            // PostCSS configuration
+            postcss: {
+                plugins: [require("autoprefixer"), require("tailwindcss")],
+                modules: {
+                    generateScopedName: "[name]__[local]___[hash:base64:5]",
+                },
+            },
+
+            // Sass configuration
+            sass: {
+                includePaths: ["node_modules"],
+                outputStyle: "compressed",
+            },
+
+            // Minification
+            minifier: "lightningcss",
+        }),
+    ],
 };
 ```
 
@@ -156,55 +154,80 @@ export default {
 import { rollupCssPlugin } from "@visulima/rollup-plugin-css";
 
 export default {
-  plugins: [
-    rollupCssPlugin({
-      // Inject CSS into JavaScript
-      mode: "inject",
-      
-      // Enable CSS modules
-      autoModules: true,
-      
-      // PostCSS with autoprefixer
-      postcss: {
-        plugins: [require("autoprefixer")],
-      },
-      
-      // Minification
-      minifier: "cssnano",
-    })
-  ]
+    plugins: [
+        rollupCssPlugin({
+            // Inject CSS into JavaScript
+            mode: "inject",
+
+            // Enable CSS modules
+            autoModules: true,
+
+            // PostCSS with autoprefixer
+            postcss: {
+                plugins: [require("autoprefixer")],
+            },
+
+            // Minification
+            minifier: "cssnano",
+        }),
+    ],
 };
 ```
 
+#### Custom Injection Package and Method
+
+You can customize the CSS injection by specifying a custom package and method:
+
+```typescript
+rollupCssPlugin({
+    mode: [
+        "inject",
+        {
+            // Use your own CSS injection library
+            package: "my-custom-injector",
+            method: "injectCSS",
+
+            // Other inject options...
+            container: "body",
+            prepend: true,
+        },
+    ],
+    autoModules: true,
+});
+```
+
+This allows you to:
+
+- Use alternative CSS injection libraries
+- Implement custom injection logic
+- Override the default `@visulima/css-style-inject` behavior
+
 ### Tailwind CSS v4 with PostCSS
 
 ```typescript
 import { rollupCssPlugin } from "@visulima/rollup-plugin-css";
 
 export default {
-  plugins: [
-    rollupCssPlugin({
-      mode: "extract",
-      autoModules: true,
-      postcss: {
-        plugins: [
-          require("@tailwindcss/postcss"),
-          require("autoprefixer"),
-        ],
-      },
-      minifier: "cssnano",
-    })
-  ]
+    plugins: [
+        rollupCssPlugin({
+            mode: "extract",
+            autoModules: true,
+            postcss: {
+                plugins: [require("@tailwindcss/postcss"), require("autoprefixer")],
+            },
+            minifier: "cssnano",
+        }),
+    ],
 };
 ```
 
 ```javascript
 // postcss.config.js
 export default {
-  plugins: {
-    "@tailwindcss/postcss": {},
-  },
-}
+    plugins: {
+        "@tailwindcss/postcss": {},
+    },
+};
 ```
 
 ### Tailwind Oxide (Rust-based)
@@ -213,21 +236,77 @@ export default {
 import { rollupCssPlugin } from "@visulima/rollup-plugin-css";
 
 export default {
-  plugins: [
-    rollupCssPlugin({
-      mode: "extract",
-      autoModules: true,
-      // Tailwind Oxide configuration
-      tailwind: {
-        oxide: true,
-        config: "./tailwind.config.js",
-      },
-      minifier: "cssnano",
-    })
-  ]
+    plugins: [
+        rollupCssPlugin({
+            mode: "extract",
+            autoModules: true,
+            // Tailwind Oxide configuration
+            tailwind: {
+                oxide: true,
+                config: "./tailwind.config.js",
+            },
+            minifier: "cssnano",
+        }),
+    ],
 };
 ```
 
+### Inline Mode
+
+Embed CSS directly as strings in JavaScript modules. This reduces HTTP requests but increases bundle size. Ideal for small CSS files or critical CSS that needs to be available immediately.
+
+```typescript
+import { rollupCssPlugin } from "@visulima/rollup-plugin-css";
+
+export default {
+    plugins: [
+        rollupCssPlugin({
+            mode: "inline",
+            autoModules: true,
+            namedExports: true,
+            minifier: "cssnano",
+        }),
+    ],
+};
+```
+
+**Benefits:**
+
+- **Zero HTTP requests** - CSS is embedded directly in JavaScript
+- **No race conditions** - CSS is available immediately when JavaScript executes
+- **Smaller initial bundle** - No separate CSS file to load
+- **Better caching** - CSS is cached with JavaScript bundle
+
+**Trade-offs:**
+
+- **Increased bundle size** - CSS content is included in JavaScript
+- **No separate caching** - CSS can't be cached independently
+- **Larger JavaScript** - Affects JavaScript parsing and execution time
+
+**Use cases:**
+
+- Critical CSS that must be available immediately
+- Small CSS files where the overhead of a separate request isn't worth it
+- Applications where CSS is dynamically generated or modified at runtime
+- Components that need their CSS to be self-contained
+
+```css
+/* Input: styles.css */
+.button {
+    background: blue;
+    color: white;
+    padding: 10px 20px;
+}
+```
+
+```javascript
+// Output: JavaScript module with embedded CSS
+var css = ".button{background:blue;color:white;padding:10px 20px;}";
+
+export { css };
+export default css;
+```
+
 ## Examples
 
 ### CSS Modules with React
@@ -273,19 +352,15 @@ declare const test: "index_test_bcd2d774";
 declare const container: "index_container_bcd2d774";
 
 interface ModulesExports {
-  'test': string;
-  'container': string;
+    test: string;
+    container: string;
 }
 
 declare const modules_c21c94f2: ModulesExports;
 
 export default modules_c21c94f2;
 
-export {
-  css,
-  test,
-  container
-};
+export { css, test, container };
 ```
 
 ### Multiple CSS Preprocessors
@@ -386,9 +461,32 @@ rollupCssPlugin({
     mode: "extract", // Creates separate CSS files
     autoModules: true,
     minifier: "cssnano",
-})
+});
 ```
 
+**Benefits:**
+
+- **Separate caching** - CSS can be cached independently from JavaScript
+- **Parallel loading** - CSS and JavaScript can load simultaneously
+- **Better performance** - Smaller JavaScript bundles, faster parsing
+- **CDN optimization** - CSS can be served from CDN with different cache strategies
+- **Selective loading** - Only load CSS for specific routes or components
+
+**Trade-offs:**
+
+- **Additional HTTP requests** - Separate CSS file must be fetched
+- **Potential FOUC** - Flash of unstyled content if CSS loads after HTML
+- **Build complexity** - Requires additional build step for CSS extraction
+- **Dependency management** - Need to ensure CSS is loaded before JavaScript execution
+
+**Use cases:**
+
+- Large CSS files where separate caching is beneficial
+- Applications with multiple CSS themes or variants
+- Production builds where performance optimization is critical
+- CDN-based deployments requiring separate asset optimization
+- Applications where CSS needs to be loaded conditionally
+
 ### Inject Mode
 
 Injects CSS directly into JavaScript at runtime. **Requires `@visulima/css-style-inject`:**
@@ -398,25 +496,164 @@ rollupCssPlugin({
     mode: "inject", // CSS embedded in JS
     autoModules: true,
     minifier: "cssnano",
-})
+});
 ```
 
+**Benefits:**
+
+- **No separate HTTP requests** - CSS is bundled with JavaScript
+- **Guaranteed availability** - CSS is always available when JavaScript executes
+- **Simplified deployment** - Single JavaScript bundle to manage
+- **Dynamic injection** - CSS can be injected conditionally or on-demand
+- **Runtime control** - Full control over when and how CSS is applied
+
+**Trade-offs:**
+
+- **Larger JavaScript bundles** - CSS content increases JavaScript file size
+- **Slower initial parsing** - JavaScript engine must process CSS content
+- **No separate caching** - CSS can't be cached independently from JavaScript
+- **Memory usage** - CSS content remains in JavaScript memory
+
+**Use cases:**
+
+- Single-page applications (SPAs) where CSS is always needed
+- Applications requiring dynamic CSS injection
+- Development builds where simplicity is preferred
+- Applications with complex CSS loading logic
+- Components that need guaranteed CSS availability
+
+#### Advanced Inject Configuration
+
+You can customize the injection behavior by passing an object to the `mode` option:
+
+```typescript
+rollupCssPlugin({
+    mode: [
+        "inject",
+        {
+            // Custom package to import the injector from
+            package: "my-custom-css-injector",
+
+            // Custom method name to import
+            method: "injectStyles",
+
+            // Container for style injection (default: "head")
+            container: "body",
+
+            // Insert styles at the beginning of container
+            prepend: true,
+
+            // Use single style tag
+            singleTag: true,
+
+            // Custom attributes for style tag
+            attributes: { "data-theme": "dark" },
+
+            // Make injector treeshakeable
+            treeshakeable: true,
+        },
+    ],
+    autoModules: true,
+    minifier: "cssnano",
+});
+```
+
+**Custom Package and Method:**
+
+- **`package`**: Override the default `@visulima/css-style-inject` package
+- **`method`**: Override the default `cssStyleInject` method name
+- **Use case**: When you want to use your own CSS injection library or have custom injection logic
+
+### Inline Mode
+
+Embeds CSS directly as strings in JavaScript modules:
+
+```typescript
+rollupCssPlugin({
+    mode: "inline", // CSS embedded as strings in JS
+    autoModules: true,
+    namedExports: true,
+    minifier: "cssnano",
+});
+```
+
+**When to use inline mode:**
+
+- Small CSS files where HTTP request overhead isn't worth it
+- Critical CSS that must be available immediately
+- Applications with dynamic CSS generation
+- Components that need self-contained styles
+
+### Emit Mode
+
+Passes processed CSS through the build pipeline without injection or extraction:
+
+```typescript
+rollupCssPlugin({
+    mode: "emit", // CSS passed through build pipeline
+    autoModules: true,
+    minifier: "cssnano",
+});
+```
+
+**Benefits:**
+
+- **Build pipeline integration** - CSS can be processed by other Rollup plugins
+- **Flexible output** - CSS can be transformed, bundled, or processed further
+- **Custom handling** - Full control over how CSS is processed and output
+- **Plugin ecosystem** - Leverage other Rollup plugins for CSS processing
+- **No assumptions** - Plugin doesn't make assumptions about CSS output
+
+**Trade-offs:**
+
+- **Manual handling required** - Need to configure other plugins to handle CSS
+- **Build complexity** - Requires understanding of Rollup plugin pipeline
+- **No automatic optimization** - CSS optimization must be handled separately
+- **Configuration overhead** - More setup required for complete CSS handling
+
+**Use cases:**
+
+- Custom CSS processing pipelines
+- Integration with other Rollup plugins
+- Applications requiring specific CSS output formats
+- Build systems with custom CSS handling logic
+- Development of CSS processing tools and plugins
+
+## Mode Comparison
+
+| Mode        | Best For                  | Bundle Size | HTTP Requests | Caching  | Complexity |
+| ----------- | ------------------------- | ----------- | ------------- | -------- | ---------- |
+| **Inject**  | SPAs, dynamic injection   | Larger JS   | Single        | Shared   | Low        |
+| **Extract** | Production, CDN           | Smaller JS  | Multiple      | Separate | Medium     |
+| **Inline**  | Small files, critical CSS | Larger JS   | Single        | Shared   | Low        |
+| **Emit**    | Custom pipelines          | Variable    | Variable      | Custom   | High       |
+
+**Quick Decision Guide:**
+
+- **Choose Inject** when you need guaranteed CSS availability and don't mind larger JS bundles
+- **Choose Extract** when performance and caching are critical, especially for production
+- **Choose Inline** when you have small CSS files and want to eliminate HTTP requests
+- **Choose Emit** when you need full control over CSS processing and output
+
 ## CSS Modules Features
 
 CSS Modules provide automatic class name scoping and TypeScript integration:
 
 ### Automatic TypeScript Declarations
+
 - **Generated .d.ts files** for full IntelliSense support
-- **Named exports** for individual class names  
+- **Named exports** for individual class names
 - **Default export** with complete module interface
 - **Build-time type checking** prevents runtime errors
 
 ### Scoped Class Names
+
 - **Automatic hashing** prevents style conflicts
 - **Deterministic naming** for consistent builds
 - **Development-friendly** class names for debugging
 
 ### Integration Benefits
+
 - **Zero configuration** - works out of the box with `.module.css` files
 - **Watch mode support** - declarations update automatically
 - **Build pipeline integration** - seamless Rollup integration
@@ -424,18 +661,21 @@ CSS Modules provide automatic class name scoping and TypeScript integration:
 ## Key Features
 
 ### Tailwind Integration
+
 - **Tailwind CSS v4** - Latest version with PostCSS integration
 - **Tailwind Oxide** - Rust-based engine for ultra-fast processing
 - **JIT compilation** - Generate only the CSS you use
 - **Smart purging** - Automatic unused style removal
 
 ### Preprocessor Support
+
 - **PostCSS** - Modern CSS transformations with extensive plugin ecosystem
 - **Sass/SCSS** - Popular CSS extension language with variables and mixins
 - **Less** - Dynamic stylesheet language with variables and functions
 - **Stylus** - Expressive, dynamic CSS preprocessor
 
 ### Performance Optimization
+
 - **Multiple minifiers** - Choose between cssnano and LightningCSS
 - **Source maps** - Full debugging support in development
 - **Code splitting** - Efficient CSS bundling strategies
@@ -448,12 +688,12 @@ Leverage the extensive PostCSS ecosystem through configuration files:
 ```javascript
 // postcss.config.js
 export default {
-  plugins: {
-    "@tailwindcss/postcss": {},
-    "autoprefixer": {},
-    "postcss-nested": {},
-  },
-}
+    plugins: {
+        "@tailwindcss/postcss": {},
+        autoprefixer: {},
+        "postcss-nested": {},
+    },
+};
 ```
 
 The PostCSS loader automatically detects and uses your PostCSS configuration.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Plugin } from 'rollup';
-import { S as StyleOptions } from './packem_shared/types-BS4hXME3.js';
-export { A as AutoModules, E as ExtractedData, I as InjectOptions, a as InternalStyleOptions, L as LightningCSSOptions, P as PostCSSConfigLoaderOptions, b as PostCSSOptions } from './packem_shared/types-BS4hXME3.js';
+import { S as StyleOptions } from './packem_shared/types-CA9pSumu.js';
+export { A as AutoModules, E as ExtractedData, I as InjectOptions, a as InternalStyleOptions, L as LightningCSSOptions, P as PostCSSConfigLoaderOptions, b as PostCSSOptions } from './packem_shared/types-CA9pSumu.js';
 import { Environment } from '@visulima/packem-share/types';
 import 'cssnano';
 import 'lightningcss';

package/dist/index.js

@@ -0,0 +1 @@
+import{default as e}from"./packem_shared/cssModulesTypesPlugin-CjGroK2y.js";import{default as u}from"./packem_shared/rollupCssPlugin-CChaHsU3.js";export{e as cssModulesTypesPlugin,u as rollupCssPlugin};

package/dist/loaders/less/index.d.ts

@@ -1,9 +1,17 @@
-// @ts-ignore
-loader;
-export { LESSLoaderOptions };
-declare namespace loader {
-    export const loader: Loader<LESSLoaderOptions>;
-    import _default = loader;
-    export { _default as default };
-}
-export = loader;
+import { c as Loader, d as LESSLoaderOptions } from '../../packem_shared/types-CA9pSumu.js';
+import 'cssnano';
+import 'lightningcss';
+import 'postcss';
+import 'postcss-load-config';
+import 'less';
+import '@visulima/packem-share/types';
+import 'sass';
+import 'sass-embedded';
+import 'stylus';
+import '@visulima/packem-share/utils';
+import 'rollup';
+import 'source-map-js';
+
+declare const loader: Loader<LESSLoaderOptions>;
+
+export { LESSLoaderOptions, loader as default };

package/dist/loaders/less/index.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var l=(s,e)=>c(s,"name",{value:e,configurable:!0});import{dirname as u,normalize as d}from"@visulima/path";import f from"less";import{readFileSync as h}from"@visulima/fs";import{resolveAlias as g}from"@visulima/path/utils";import{resolve as y}from"../../packem_shared/resolve-anj9ucIq.js";import{normalizeUrl as F,getUrlOfPartial as v}from"../../packem_shared/hasModuleSpecifier-DIZeev_W.js";var b=Object.defineProperty,m=l((s,e)=>b(s,"name",{value:e,configurable:!0}),"i");const M=[".less",".css"],x=m((s,e)=>new class extends s.FileManager{supports(){return!0}async loadFile(r,a,t){const i=F(g(r,e)),o=v(i),n={baseDirs:[],caller:"Less importer",extensions:M};Array.isArray(t.paths)&&n.baseDirs.push(...t.paths),n.baseDirs.push(a);const p=y([o,i],n);return{contents:h(p),filename:p}}},"getStylesFileManager"),A=m(s=>({install(e,r){r.addFileManager(x(e,s))}}),"importer"),U={name:"less",async process({code:s,map:e}){const r=[A(this.alias)];this.options.plugins&&r.push(...this.options.plugins);const a=f.render,t=await a(s,{...this.options,filename:this.id,plugins:r,sourceMap:{outputSourceFiles:!0,sourceMapBasepath:u(this.id)}}),i=t.imports;for(const o of i)this.deps.add(d(o));return{code:t.css,map:t.map??e}},test:/\.less$/i};export{U as default};

package/dist/loaders/lightningcss.d.ts

@@ -1,4 +1,4 @@
-import { c as Loader, L as LightningCSSOptions } from '../packem_shared/types-BS4hXME3.js';
+import { c as Loader, L as LightningCSSOptions } from '../packem_shared/types-CA9pSumu.js';
 import 'cssnano';
 import 'lightningcss';
 import 'postcss';
@@ -14,4 +14,4 @@ import 'source-map-js';
 
 declare const lightningCSSLoader: Loader<LightningCSSOptions>;
 
-export = lightningCSSLoader;
+export { lightningCSSLoader as default };

package/dist/loaders/lightningcss.js

@@ -0,0 +1,3 @@
+import{transform as r,browserslistToTargets as a}from"lightningcss";import{n as o}from"../packem_shared/ensure-auto-modules-BU3xWEjl.js";const l={name:"lightningCSS",async process({code:t,map:i}){let s=!1;typeof this.options.modules=="boolean"?s=this.options.modules:typeof this.options.modules=="object"&&(s=o(this.options.modules.include,this.id)),this.autoModules&&this.options.modules===void 0&&(s=o(this.autoModules,this.id));const e=r({...this.options,code:Buffer.from(t),cssModules:this.options.modules??s,filename:this.id,inputSourceMap:i,minify:!1,sourceMap:!this.sourceMap,targets:a(this.browserTargets)});return e.warnings.length>0&&this.logger.warn({message:`warnings when transforming css:
+${e.warnings.map(n=>n.message).join(`
+`)}`}),{code:e.code.toString(),map:e.map?JSON.parse(Buffer.from(e.map).toString()):void 0,moduleSideEffects:s||typeof this.inject=="object"&&this.inject.treeshakeable?!1:"no-treeshake"}},test:/\.css$/i};export{l as default};

package/dist/loaders/postcss/index.d.ts

@@ -1,4 +1,4 @@
-import { c as Loader, a as InternalStyleOptions } from '../../packem_shared/types-BS4hXME3.js';
+import { c as Loader, a as InternalStyleOptions } from '../../packem_shared/types-CA9pSumu.js';
 import 'cssnano';
 import 'lightningcss';
 import 'postcss';
@@ -14,4 +14,4 @@ import 'source-map-js';
 
 declare const loader: Loader<NonNullable<InternalStyleOptions["postcss"]>>;
 
-export = loader;
+export { loader as default };