babel-plugin-namespace

A babel plugin to enable namespacing and rewrite these namespace as an alias for directories as different directories during the Babel process.

Description

Instead of using relative paths in your project, you'll be able to use a namespace to allow you to require a dependency in a way that is more loosely coupled to the directory structure on disk.

Note:

• In this plugin when say namespace, it's actually just a module alias to translate path of your module from the directory structure on disk. So please don't be confused with it.
• This plugin also work with require() function.
• If you're using eslint-plugin-import, you should use eslint-import-resolver-babel-namespace to avoid having false errors.

Usage Instructions

Requirements

This is a Babel plugin so it requires Babel v6 to run.

Installation

Install the plugin

$ npm install -D babel-plugin-namespace

Usage

Given the directory structure:

app
|__ .babelrc
|__ foo
|   |__ bar
|       |__baz.js
|__ src
|   |__ models
|       |__ User.js
|   |__ controllers
|       |__ User.js
|__ package.json

Specify the plugin in your .babelrc with the custom configuration.

{
  "plugins": [
    "namespace"
  ]
}

In package.json:

The most important things in your package.json is the name field

{
  "name": ["my-package"]
}

Then the plugins will generate the source maps:

{
  "my-package": [
    "/(...realpath-of...)/my-package/src"
  ],
  "my-package/foo": "/(...realpath-of...)/my-package/foo"
}

Example:

In src/controllers/User.js:

// Instead of using this;
import UserModel from '../models/User';

// Use that:
import UserModel from 'my-package/models/User';

// => resolves: '../models/User.js';
// NOTE: "my-package" is come from your package.json

// Instead of using this;
import baz from '../../foo/bar/baz';

// Use that:
import baz from 'my-package/foo/bar/baz';

// => resolves: '../../foo/bar/baz.js';
// NOTE: "foo" directory is created by "includes" field from our configuration

If you've a very, very long package name. This plugin also supports sign expansion.

• Tilde (~) (Use at your own risk)

import baz from '~/foo/bar/baz';

// => resolves: '../../foo/bar/baz.js';

// You can also remove the first path separator
import baz from '~foo/bar/baz';

// => resolves: '../../foo/bar/baz.js';

• Colon (:)

import baz from ':/foo/bar/baz';

// => resolves: '../../foo/bar/baz.js';

// You can also remove the first path separator
import baz from ':foo/bar/baz';

// => resolves: '../../foo/bar/baz.js';

Options

Use Babel's plugin options by replacing the plugin string with an array of the plugin name and an object with the options:

{
  "plugins": [
    ["namespace", {
      "disableSync": false,
      "sources": [
        "src"
      ],
      "includes": [
        "foo"
      ],
      "excludes": [
        "node_modules"
      ],
      "namespaces": {
        "test": "tests",
        "foo/bar/baz": "path/to/foo/bar/baz",
      }
    }]
  ]
}

From these options the plugins will generate the source maps:

{
  "my-package": [
    "/(...realpath-of...)/my-package/src"
  ],
  "my-package/foo": "/(...realpath-of...)/my-package/foo",
  "foo/bar/baz": "/(...realpath-of...)/my-package/path/to/foo/bar/baz",
  "test": "/(...realpath-of...)/my-package/path/to/foo/bar/tests"
}

These options are currently available:

Field	Type	Default	Description
disableSync	Boolean	false	If true, doesn’t actually includes all directories in the first depth of your project root directory. See: includes
sources	`String	Array`	src
includes	`String	Array`	depth + 1
excludes	`String	Array`	node_modules
namespaces	Object	{}	The keys of the namespaces object will be used to match against as an import statement. To use a namespace in a file, simply place the name of the namespace in your import statement and continue writing the path from there.

Why use babel-plugin-namespace?

It's up to you. There's nothing wrong with the current import system. Regardless, you may still consider it useful to namespace your modules under a name of your choosing, such as M or $, freeing up those "global" modules for use without conflicts.

License

MIT, see LICENSE for details.