@plumeria/next-plugin

@plumeria/next-plugin is a plugin for using Plumeria with Next.js. It supports both Turbopack and Webpack for Next.js and provides style compilation and HMR (Hot Module Replacement) at build time.

Installation

Terminal

pnpm i -D @plumeria/next-plugin

Usage

Wrap your configuration using withPlumeria in next.config.ts or next.config.js.

next.config.ts

import type { NextConfig } from "next";
import { withPlumeria } from "@plumeria/next-plugin";

const nextConfig: NextConfig = {
  // Existing configuration
};

export default withPlumeria(nextConfig);

API

`withPlumeria(nextConfig, options)`

Takes a Next.js configuration object and returns a new configuration object with the necessary Turbopack or Webpack configurations added for Plumeria.

nextConfig: Next.js configuration object.
options: Compiler options, passed through to the loader, and lint.

function withPlumeria(nextConfig: NextConfig, options?: PlumeriaOptions): NextConfig;

Options

next.config.ts

export default withPlumeria(nextConfig, {
  include: ['./src/**/*.{ts,tsx}'],
  exclude: ['**/node_modules/**', '**/.next/**'],
  styleProp: 'sx',
});

include: Globs the stylesheet is compiled from. The default is every js/jsx/ts/tsx file.
exclude: Globs excluded from that compilation. The default is node_modules, dist and .next.
styleProp: The JSX prop that carries styles. The default is 'classStyle'.
withoutLogicalProperties: Rejects the logical name of a property that also has a physical name. The default is false.
withoutPhysicalProperties: Rejects the physical name of a property that also has a logical name. The default is false.
lint: Lints the project with @plumeria/eslint-plugin during next build. The default is true.

interface PlumeriaOptions {
  include?: string[];
  exclude?: string[];
  styleProp?: string;
  withoutLogicalProperties?: boolean | { sizes?: boolean };
  withoutPhysicalProperties?: boolean | { sizes?: boolean };
  lint?: boolean;
}

styleProp

Renaming the prop takes two steps, and they have to agree. Tell the plugin:

next.config.ts

export default withPlumeria(nextConfig, { styleProp: 'sx' });

and declare the same name for TypeScript; see Declaring the styling prop.

If the two disagree, the prop type-checks but is never compiled away. @plumeria/eslint-plugin reads the same name from settings.plumeria.styleProp.

withoutLogicalProperties and withoutPhysicalProperties

These reject one spelling of a property that has both a logical and a physical name. They behave exactly as on @plumeria/unplugin, which covers the error, the { sizes } option and the lint rule each direction has to match:

next.config.ts

export default withPlumeria(nextConfig, { withoutPhysicalProperties: true });

next.config.ts

export default withPlumeria(nextConfig, {
  withoutPhysicalProperties: { sizes: true },
});

lint

The lint is integrated into the build by default, so it needs no setup. next build runs @plumeria/eslint-plugin through oxlint alongside the compile and stops on any error or warning. The build waits for the lint before it exits, so a build that finishes first still fails when the lint does. next dev does not lint.

The lint runs the recommended rules, and withoutLogicalProperties or withoutPhysicalProperties adds the spelling rule that matches, { sizes } included. styleProp reaches the rules that read the styling prop. It does not read eslint.config.*.

oxlint skips the files .gitignore ignores, and runs only the Plumeria rules, not oxlint's own.

plumeria-lint -- next build still works, and the lint runs once. To build without it:

next.config.ts

export default withPlumeria(nextConfig, { lint: false });

On this page