Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

file-replace-loader

Package Overview
Dependencies
Maintainers
1
Versions
17
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

file-replace-loader

file-replace-loader is webpack loader that allows you replace files in compile time

  • 1.4.2
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
3.7K
decreased by-38.39%
Maintainers
1
Weekly downloads
 
Created
Source

file-replace-loader

version npm downloads license

file-replace-loader is webpack loader that allows you replace files in compile time by some condition.

file-replace-loader is free and will always remain free
A simple and quick way to support the project is to buy me a coffee.
It will take no more than 5 minutes and will allow the project to keep going

Buy me a coffee

Table of contents

Features

  • Compatibility with webpack 3.x, 4.x, 5.x;
  • Support watch webpack mode;
  • Replace files in compile time without change source files;
  • Multiple replacement;
  • Sync and async modes;
  • Compatibility with other loaders;
  • Support binary files.

Installation

NPM

npm install --save-dev file-replace-loader

Yarn

yarn add file-replace-loader

Usage

const { resolve } = require('path');

module.exports = {
  //...
  module: {
    rules: [{
      test: /\.config\.js$/,
      loader: 'file-replace-loader',
      options: {
        condition: 'if-replacement-exists',
        replacement: resolve('./config.local.js'),
        async: true,
      }
    }]
  }
}

This example rule replaces all of imports /\.config.js$/ to config.local.js file,
if replacement exists (condition if-replacement-exists).

After this build a bundle file will contain code from config.local.js and original sources won't changed.

Multiple replace

To describe replace rules for two or more files you can use function as replacement value.

How does it work?

  1. Webpack runs file-replace-loader according to test rule, include and exclude rule options;
  2. file-replace-loader looks on replacement option. If it is string then the loader just replace a file. If it is a function then file-replace-loader checking what it returns. If the function returns a path to file then the loader replaces, if returns nothing then current match skips.
  3. If replacement function returns a path then file-replace-loader looks to condition. If condition is always then it replace every match. If condition is if-replacement-exists then loader checking existing file, etc;

For example:

const { resolve } = require('path');

module.exports = {
  //...
  module: {
    rules: [{
      test: /\.js$/,
      loader: 'file-replace-loader',
      options: {
        condition: 'always', // <-- Note that the rule applies for all files!
        replacement(resourcePath) {
          if (resourcePath.endsWith('foo.js')) {
            return resolve('./bar.js');
          }
          if (resourcePath.endsWith('foo-a.js')) {
            return resolve('./bar-a.js');
          }
        },
        async: true,
      }
    }]
  }
}

file-replace-loader passes to replacement function resourcePath for every matching. file-replace-loader doesn't care what developer does with this path but if repalcement function returns a new path then file-replace-loader replaces file. If replacement function returns nothing then file-replace-loading skip replace for current resourcePath.

Example with mapping:

const { resolve } = require('path');

module.exports = {
  //...
  module: {
    rules: [{
      test: /\.js$/,
      loader: 'file-replace-loader',
      options: {
        condition: 'always', // <-- Note that the rule applies for all files! But you can use other conditions too
        replacement(resourcePath) {
          const mapping = {
            [resolve('./src/foo-a.js')]: resolve('./src/bar-a.js'),
            [resolve('./src/foo-b.js')]: resolve('./src/bar-b.js'),
            [resolve('./src/foo-c.js')]: resolve('./src/bar-c.js'),
          };
          return mapping[resourcePath];
        },
        async: true,
      }
    }]
  }
}

NOTE: Make shure that all replacement files contains necessary imports and exports that other files are expecting.

Using with binary files

file-replace-loader allows replace binary files.
For example:

//webpack.config.js

const { resolve } = require('path');

module.exports = {
  //...
  module: {
    rules: [{
      test: /\.png$/,
      use: [{
        loader: 'file-loader',
        options: {
          name: '[name].[ext]',
        },
      }, {
        loader: 'file-replace-loader',
        options: {
          condition: 'if-replacement-exists',
          replacement: resolve('./src/replacement.png')
        }
      }]
    }]
  }
}

Using with other loaders

file-replace-loader must executes before other loaders. This means that in webpack config file the loader must be last in list.
For example:

//webpack.config.js

const { resolve } = require('path');

// Correct

module.exports = {
  //...
  module: {
    rules: [{
      test: /\.config\.js$/,
      use: [{
        loader: 'babel-loader',
      }, {
        loader: 'file-replace-loader',
        options: {
          condition: 'if-replacement-exists',
          replacement: resolve('./config.local.js'),
          async: true,
        }
      }]
    }]
  },
}

Above is correct example. file-replace-loader will executed before other loaders.
Let's see incorrect usage:

//webpack.config.js

const { resolve } = require('path');

// Error, because file-replace-loader will be execute after other loaders

module.exports = {
  //...
  module: {
    rules: [{
      test: /\.config\.js$/,
      use: [{
        loader: 'file-replace-loader',
        options: {
          condition: 'if-replacement-exists',
          replacement: resolve('./config.local.js'),
          async: true,
        }
      }, {
        loader: 'babel-loader',
      }]
    }]
  },
}

In incorrect example above file-replace-loader first in rule list. This case throw an error because file-replace-loader should be last in list.

Loader options

OptionTypeRequiredDefaultPossible values
condition
Condition to replace
string|booleanno'if-replacement-exists'true,
false,
'always',
'never',
'if-replacement-exists',
'if-source-is-empty'
replacement
Replacement file
string|function (resourcePath, options)yesFull path to file or function returning full path to file
async
Asynchronous file reading
booleannotruetrue,
false
progress
Progress output
booleannoIS_DEBUG_MODE == true or IS_PROGRESS_MODE == truetrue,
false

Contributing

See contributing guideline.

License

MIT LICENSE

Keywords

FAQs

Package last updated on 24 Apr 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc