All make*Transform() functions will automatically load configuration for your transform and make it available via transformOptions.config (and through the more detailed transformOptions.configData.)

Configuration is taken first from data passed via options from browserify (either from b.transform(tr, opts) or from the command line. Configuration is then loaded from package.json. If configuration is found in both package.json and in data passed programatically, then keys from the programatic configuartion are copied over top of the configuration from package.json.

All transforms created by make*Transform() receive configuration via transformOptions.configData. The configData object has the following properties:

• configData.config - The configuration for the transform.
• configData.configDir - The directory the configuration was loaded from; the directory which contains package.json if that's where the config came from, or the directory which contains the file specified in package.json. This is handy for resolving relative paths. Note that this field may be null if the configuration is set programatically.
• configData.configFile - The file the configuration was loaded from. Note that this field may be null if the configuration is set programatically.
• configData.cached - Since a transform is run once for each file in a project, configuration data is cached using the location of the package.json file as the key. If this value is true, it means that data was loaded from the cache.
• configData.appliesTo - The appliesTo from the configuration, if one was present. See below.

All modules that rely on browserify-transform-tools can contain a configuration item called 'appliesTo'. This will configure what files the transform will be applied to. For example, users of the "soupify" transform might add the following to their package.json:

"soupify": {
    "appliesTo": {"includeExtensions": [".js"]}
}

This will make soupify apply to all '.js' files, and only to '.js' files, regardless of what was specified in the transform's options.

appliesTo should include exactly one of the following:

• appliesTo.includeExtensions - A list of extensions to process. If this option is not specified, then all extensions will be processed. If this option is specified, then any file with an extension not in this list will skipped.

• appliesTo.excludeExtensions - A list of extensions which will not be processed. e.g. "['.coffee', '.jade']"

• appliesTo.files - A list of paths, relative to the configuration file, of files which should be transformed. Only these files will be transformed. This is handy for transforms like includify which you typically only apply to one or two files in your project; defining this will typically speed up your bundle time, since you no longer are running the transform on all the files in your project.

• appliesTo.regex - A regex or a list of regexes. If any regex matches the full path of the file, then the file will be processed, otherwise not.

The appliesTo key will be stripped from the configuration before being passed to your transform (although it is available in the configData if you need it for some reason.) Note that appliesTo will override the includeExtensions and excludeExtensions provided to any of the make*Transform() functions.

As of v1.3.1, browserify-transform-tools will load arguments passed via browserify's API or on the command line using the subarg syntax. This is the best way for users to pass configuration to your transform.

The default behavior when looking for package.json is to start from the current working directory, walk up the directory tree until package.json is found, then load the configuration from that file.

If options.fromSourceFileDir is set, then instead the behavior is to start at the source file, walk up the directory tree until package.json is found, and try to load configration from that file. If configuration is not found, then we will continue to walk up the tree until we find another package.json and will try again, recursively. This is similar to how browserify-shim looks for configuration, and was the default in browserify-transform-tools v1.x. See this issue for further details.

Once package.json is found, configuration is loaded by finding a key in the package.json with the same name as your transform. For example, for a "unbluify" transform, you might set up your package.json to look like:

{
    "name": "myProject",
    "version": "1.0.0",
    ...
    "unbluify": {"newColor": "red"}
}

Or alternatively you can set the "unbluify" key to be a js or JSON file:

{
    "unbluify": "unbluifyConfig.js"
}

And then configuration will be loaded from that file:

module.exports = {
    newColor: "red"
};

Note using a .js file means you can use environment variables to make changes to your configuration. You can also use .coffee files if you are using the Browserify API, and require('coffee-script'); before you do your bundle.

If you are writing your own transform which doesn't use a make*Transform() function, you can still use browserify-transform-tools to load configuration from package.json:

var transformTools = require('browserify-transform-tools');

transformTools.loadTransformConfig('myTransform', file, function(err, configData) {
    var config = configData.config;
    var configDir = configData.configDir;
    ...
});

Or synchronously via:

var configData = transformTools.loadTransformConfigSync(...);

There is also a skipFile() function available for deciding whether or not you should process a file, based on the current configuration:

    var configData = transformTools.loadTransformConfigSync(...);
    var shouldSkipFile = transformTools.skipFile(filename, configData);

If your users are using the browserify API to bundle their apps, then they can specify the configuration by calling into the configure(config, options) on your transform. This function is created automatically on any transform returned by the make*Transform() functions.

configure() will override any configuration set in package.json. configure() returns a new transform instance and does not modify the existing transform:

myTransform = require('myTransform').configure(
    {colorFile: './colors.json'},
    {configFile: __filename});

If want to modify the configuration on an existing instance, you can call setConfig() with the same options. For example:

myTransform = require('myTransform');
myTransform.setConfig(
    {colorFile: './colors.json'},
    {configFile: __filename});

Both functions take the following options:

• options.configFile - The file where configuration was loaded from. Used to set configData.configFile and configData.configDir in the configuration passed to the transform.
• options.configDir - The directory containing the configFile (not needed if options.configFile is specified). Used to set configData.configDir in the configuration passed to the transform.