@modular-css/rollup-rewriter

Rewrite dynamic imports so they automatically load their CSS dependencies using JS chunk -> CSS chunk dependency information from modular-css. Avoid the dreaded FOUC automatically without having to manually juggle CSS files & JS chunks.

Turn this:

const module = await import("./expensive-styled-module.js");

into this

const module = await Promise.all([
    lazyload("./expensive-styled-module.css"),
    import("./expensive-styled-module.js")
])
.then((result) => result[result.length - 1]);

• Install
• Limitations
• Usage
• Options

Install

> npm i @modular-css/rollup-rewriter

⚠ Limitations ⚠

This plugin does not yet do everything for you instantly and perfectly. Maybe someday! Here's a list of current limitations:

• Only supports some of the rollup output format values.
  • Currently es, esm, amd, and system.
• Doesn't dynamically add the loader option into the module so it can be inlined or extracted by rollup.
  • It's just injected at the top of the module scope, so you can't depend on packaging yet. Can't be injected earlier because the full module dependency tree & chunks must be known first.
  • Probably easier to ensure it's available globally and only use loadfn.
• Doesn't allow for adjusting URLs to add a CDN-prefix or anything else.
  • This would be straightforward, just not implemented yet. A PR would be very welcome!

Usage

API

const bundle = await rollup({
    input   : "./index.js",
    plugins : [
        require("@modular-css/rollup")(),
        require("@modular-css/rollup-rewriter")({
            loadfn : "...",
        }),
    ],
});

Config file

import css from "@modular-css/rollup";
import rewrite from "@modular-css/rollup-rewriter";

export default {
    input   : "./index.js",
    output  : {
        dest    : "./gen/bundle.js",
        format  : "umd"
    },
    plugins : [
        css(),
        rewrite({
            loadfn : "...",
        }),
    ],
};

Options

loader (string|function)

The loader option can be set if you want the plugin to inject a reference to a CSS loader that returns a promise (I like lazyload-css). This loader must be available statically, so this option is most useful in es/esm mode where it can be loaded via import. If given a function instead of a string that function will be called once per chunk being modified, it gets passed a single argument of the form { chunks } where chunks is the raw rollup output chunks.

loadfn (string)

The name of the promise-returning function that will be used to load CSS. The function will be passed the path to the CSS file and is expected to return a promise that resolves once the file is loaded.

The loadfn option is required.

verbose (boolean)

When enabled will cause the plugin to output more information about the processing as it occurs.