Rollup-plugin-relative-to-package NPM

Rollup-Plugin-Relative-To-Package

Converts unit tests that use relative imports to use package imports. Along the way, it calculates which files are external from Rollup's perspective. Therefore, the external field is not required in your configuration.

NOTE: Since Node v13.6.0 and v12.16.0, Node supports 'self-referencing', where a module (e.g. a unit test), can import the package module using the package name instead of relative imports. In most (all?) cases, you should be using that feature instead of this plugin. This plugin only processes relative imports. Therefore, if you are using self-referencing imports, this plugin will not affect your Rollup builds.

Here is what the plugin does. Given a unit test that uses relative imports:

import YourPackage from '../src/your-package-module.js'
import { internalFunction } from '../src/inside-your-package.js'
/* Unit test code goes here */

Convert it to look like this:

import YourPackage from 'your-package-name'
import { internalFunction } from 'your-package-name/src/inside-your-package'
/* Unit test code goes here */

Installation

Using npm:

npm install --save-dev rollup-plugin-relative-to-package

Upgrading To 1.0.0

Version 1.0.0 makes breaking changes to this plugin.

Options extensions, module, mainFields, and modulePaths are no longer supported. In their place are the exports and conditions fields. The exports field is the same as the package.json exports field, and conditions specifies what subPaths are valid.

The simplest way to upgrade is to add an exports field in your package.json, and remove the existing options from your Rollup configuration. You may need to add the conditions field if you use special export conditions.

The plugin is now a dual module so you can use it from CommonJS and ECMAScript modules.

Use

Create a rollup configuration file, and import the plugin.

import relativeToPackage from 'rollup-plugin-relative-to-package'

export default {
  // This is the entry point to your unit test - not your package!
  // I use the 'multi-entry' plugin to process all unit tests at once.
  input: 'test/unit-test.js',
  // relativeToPackage determines which packages are external, and
  // gives that information to Rollup. So there is no need to specify it.
  // external: []
  output: {
    dir: 'output',
    format: 'es'
  },
  plugins: [
    // usually, the default values should work just fine
    relativeToPackage({
      conditions: ['default', 'node', 'import', 'production']
    })
  ]
}

Then call Rollup however you wish.

This plugin dynamically determines which packages are external, and tells Rollup. For example, this plugin will detect import _ from 'lodash' as an external import. There is no need to set the Rollup external input option.

This example Rollup configuration in the root of this repository uses this plugin to generate a unit test that imports the package. Here's how to run it:

pnpm install # I use pnpm. You can use npm and npx if you like
pnpx rollup -c rollup.config.js # will produce test-bundle.js

The check:packfile script in package.json uses this plugin to test the package. The configuration file for check:packfile is rollup.test.config.js. It requires pnpm. Run the script like this:

# PNPM must be installed
pnpm install
pnpm run build
pnpm run check:packfile

Options

The plugin works without options. It will look at the closest package.json file to determine the packageName and exports option values. It is possible that you'll want to provide the conditions option if the default values are not sufficient.

conditions

Type: Array[...String]
Default: ['default', 'import', 'node', 'node-addons']

This option completely replaces the default conditions - it does not append to the default conditions. Therefore include all the conditions you need.

The Node documentation describes conditional exports. This option provides the conditions that this plugin will use to resolve the module specifier when it encounters a relative path.

exports

Type: Object
Default: by default exports is loaded from the nearest package.json

Use this option if the exports field in your package.json is not suitable for some reason. The exports field is documented in the Node documentation.

NOTE: This plugin uses the exports field in reverse. It uses a module URI (e.g. filepath) to lookup the associated subPath and then generate the import module specifier. That means that this plugin implemented the exports field evaluation process, and there might be bugs - please report them. This plugin exports a class ExportsResolver that implements forward and backward lookup if that helps.

packageName

Type: String
Default: read from the nearest package.json

This value is the package name to use when replacing relative imports with package imports.

The default packageName is determined by looking at the name field of package.json. The search for package.json is controlled by the rootDir option.

rootDir

Type: String
Default: process.cwd()

If you do not specify the exports or packageName options, this plugin needs to look at package.json to figure out the right values. It will start looking for package.json at the rootDir value, and continue up the directory structure until it finds one, or stops at the file system boundary. If your package.json is somewhere else, set this option.