external-url-loader

External-url-loader

A loader for webpack that permit static's usage as externals that make reference to your own package. If those statics not exceed the limit size you specify, it will be encoded in base64.

The loader will generate a path with a require that make reference to the packageName you specify.

This is useful when you want to create a library that use statics dependencies.

Getting Started

To begin, you'll need to install external-url-loader:

$ npm install external-url-loader --save-dev

This loader provides the same feature as url-loader and extends all url-loader options.

import img from './image.png';

// webpack.config.js
module.exports = {
    module: {
        rules: [
            {
                test: /\.(png||jpe?g|gif|svg)$/i,
                use: [
                    {
                        loader: 'external-url-loader',
                        options: {
                            limit: 8192, // url-loader limit
                            packageName: 'library-package-name', // your package name
                            active: process.env.NODE_ENV === 'production', // if you want to enable or disable external-url-loader and fallback on url-loader
                        },
                    },
                ],
            },
        ],
    },
};

More over you have to add your own library, and all sub paths as externals in your build process.

:warning: Don't put externals in your dev-server process. (you can make another config dedicated to dev-server)

// webpack.config.js
module.exports = [
    {
        module:  ...,
        name: 'build',
        externals: [
            new RegExp(`^library-package-name.*$`)
        ]
    },
    {
        module:  ...,
        name: 'dev-server',
    },
];

Options

packageName

Type: String Default: undefined

This is your package name that's will use in the generated path.

active

Type: Boolean Default: undefined

If you want to disabled the externals require and fallback on url-loader (a non production task for example)

extractCss

Type: Boolean Default: undefined

To generate a specific path for extracted css, if you use it with css-loader and MiniCssExtractPlugin during production process. You have to make a specific rule for css issuer and active this option.

It will generate a path like ~library-package-name/image.png

import img from './image.png';

// webpack.config.js
module.exports = {
    module: {
        rules: [
            {
                test: /\.(png||jpe?g|gif|svg)$/i,
                issuer: /\.(css|scss|less)$/i,
                use: [
                    {
                        loader: 'external-url-loader',
                        options: {
                            limit: 8192,
                            packageName: 'library-package-name', // your package name.
                            active: process.env.NODE_ENV === 'production', // if you want to enable or disable external-url-loader and fallback on url-loader.
                            extractCss: process.env.NODE_ENV === 'production', // if you want to enable or disable path generation for css extraction.
                        },
                    },
                ],
            },
            {
                test: /\.(png||jpe?g|gif|svg)$/i,
                issuer: /\.(js|jsx|ts|tsx)$/i,
                use: [
                    {
                        loader: 'external-url-loader',
                        options: {
                            limit: 8192,
                            packageName: 'library-package-name', // your package name.
                            active: process.env.NODE_ENV === 'production', // if you want to enable or disable external-url-loader and fallback on url-loader.
                        },
                    },
                ],
            },
        ],
    },
};

others:

All other options come from url-loader option

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT