@nocojs/rollup-plugin

Rollup/Vite plugin that scans for placeholder() calls imported from nocojs, generates placeholders (and optional cache entries) via @nocojs/core, and inlines the results at build time.

Installation

# application dependency
npm install nocojs

# dev dependency for your build pipeline
npm install --save-dev @nocojs/rollup-plugin

Usage

Basic Usage

// rollup.config.js
import { rollupNocoPlugin } from '@nocojs/rollup-plugin';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    rollupNocoPlugin()
  ]
};

In your application code import the helper from nocojs:

import { placeholder } from 'nocojs';

export function HeroImage() {
  return <img src={placeholder('/images/hero.jpg')} alt="Hero" />;
}

The plugin replaces the function call with a data URI during the build.

With Custom Options

// rollup.config.js
import { rollupNocoPlugin } from '@nocojs/rollup-plugin';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    rollupNocoPlugin({
      // Directory where static assets are served from
      publicDir: 'public',
      
      // Directory for nocojs cache files
      cacheFileDir: '.nocojs',
      
      // File patterns to include (supports glob patterns)
      include: [
        '**/*.{js,jsx,ts,tsx,vue,svelte}', // Process all matching files
        'src/**/*.{js,ts}',                // Only process JS/TS files in src
        '**/components/**/*.tsx'           // Only TSX files in components dirs
      ],
      
      // File patterns to exclude (supports glob patterns)
      exclude: [
        '**/node_modules/**',              // Exclude node_modules
        '**/*.test.{js,ts,tsx}',          // Exclude test files
        '**/dist/**'                       // Exclude build output
      ],
      
      // Placeholder type for images
      placeholderType: 'blurred',
      
      // Enable caching
      cache: true,
      
      // Log level
      logLevel: 'info',
      
      // Default dimensions
      width: 12, 
      // height: 12 /* If either height or width is provided, the image will be resized with the aspect ratio preserved */
      wrapWithSvg: true, // Whether to wrap the generated preview in an SVG to keep aspect ratio.
    })
  ]
};

Options

publicDir

• Type: string
• Default: 'public'

Directory where static assets are served from.

cacheFileDir

• Type: string
• Default: '.nocojs'

Directory where nocojs cache files are stored.

include

• Type: string[]
• Default: ['**/*.{js,jsx,ts,tsx,vue,svelte}']

File patterns to include for processing. Supports glob patterns powered by picomatch.

Examples:

• ['**/*.{js,ts}'] - Process all JS/TS files
• ['src/**/*.tsx'] - Process only TSX files in src directory
• ['**/components/**/*.{js,jsx}'] - Process JS/JSX files only in components directories

exclude

• Type: string[]
• Default: ['**/node_modules/**']

File patterns to exclude from processing. Supports glob patterns powered by picomatch.

Examples:

• ['**/node_modules/**'] - Exclude node_modules
• ['**/*.test.{js,ts}'] - Exclude test files
• ['**/dist/**', '**/.next/**'] - Exclude build directories

placeholderType

• Type: 'normal' | 'blurred' | 'grayscale' | 'dominant-color' | 'average-color' | 'transparent'
• Default: 'blurred'

Type of placeholder to generate for images.

replaceFunctionCall

• Type: boolean
• Default: undefined

Whether to replace function calls in the transformed code.

cache

• Type: boolean
• Default: undefined

Enable or disable caching of processed images.

width

• Type: number
• Default: undefined

Default width for image processing.

height

• Type: number
• Default: undefined

Default height for image processing.

logLevel

• Type: 'error' | 'info' | 'none' | 'verbose'
• Default: undefined

Log level for the transformation process.

Example

Before transformation:

import { placeholder } from 'nocojs';
// src/App.jsx
function App() {
  return (
    <div>
      <img src={placeholder('https://example.com/image.jpg')} alt="Example" />
    </div>
  );
}

After transformation (conceptual):

function App() {
  return (
    <div>
      <img
        src="data:image/svg+xml;base64,..."
        alt="Example"
      />
    </div>
  );
}

License

MIT

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

Related

• nocojs - Public API package (placeholder, getPlaceholder, getOptimizedImage)
• @nocojs/core - Transformer and server utilities