npm

Use

The npm plugin makes it easy to work with npm packages. By pointing it at a package.json, you will be able to import npm packages as modules.

By default, if stealPath points to steal.js within node_modules like:

<script src="../node_modules/steal/steal.js" main></script>

configMain will point to "package.json!npm". The npm plugin reads package.json and sets a normalize and locate hook.

Note: if you are using npm 3 see the npmAlgorithm option below.

npm Module names

Package dependency module names are converted to look like:

packageName@version#modulePath!pluginName

For example, code that import's jQuery like:

import $ from "jquery"

might actually import:

jquery@2.1.3#dist/jquery.js

Configuration

package.json configures the behavior of a package and even dependency packages. This section lists the configurable properties and behaviors that steal uses.

package.main

Specifies the main property unless it is overwritten by package.browser or package.steal.main.

{
  "main": "myapp"
}

package.browser

Specifies browser-specific overwrites for module file resolution. This behaves like Browserify's browser field.

{
  "browser": {
    "fs": "level-fs",
    "./lib/ops.js": "./browser/opts.js"
  }
}

package.globalBrowser

Global browser specific overwrites for module file resolution. These mapping take effect for all projects. Use sparingly.

{
  "globalBrowser": {
    "console": "console-browserify",
    "constants": "constants-browserify"
  }
}

package.steal

By default, any property on the package.steal object is passed to config. However, the following properties have special behavior:

package.steal.main

The moduleName of the initial module that should be loaded when the package is imported. For example:

{
  "name": "my-module",
  "version": "1.2.3",
  "steal": {
    "main": "my-main"
  }
}

When my-module is imported, my-module@1.2.3#my-main will be the actual module name being imported. This path that my-main will be found depends on the directories.lib setting.

package.steal.map

The map config works similar to the base map behavior. However, both the keys and values are converted to npm module names. The keys and values must:

• Start with ./ to map modules within the package like "./src/util", or
• Look like packageName#./modulePath to map direct dependencies of the package.

{
  "steal": {
    "map": {
      "./util/util": "./util/jquery/jquery",
      "jquery" : "lodash"
    }
  }
}

package.steal.meta

The meta config works similar to the base meta behavior. However, the module names must:

• Start with ./ to add metadata to modules within the package like "./src/util", or
• Look like packageName#./modulePath to add metadata to direct dependencies of the package.

Example:

{
  "steal": {
    "meta": {
      "./src/utils": {"format": "amd"},
      "jquery": {"format": "global"},
      "lodash#./array/grep": {"format": "es6"}
    }
  }
}

package.steal.npmIgnore

Use npmIgnore to prevent package information from being loaded for specified dependencies in the peerDependencies, devDependencies or dependencies. The following ignores a package.json's devDependencies and cssify. But all other dependencies will be loaded:

{
  "dependencies": {
    "can": "2.2.4",
    "cssify": "^0.6.0"
  },
  "devDependencies": {
    "steal-tools": "0.5.0"
  },
  "steal": {
    "npmIgnore": ["devDependencies","cssify"]
  }
}

The following packages are ignored by default:

• "steal", "steal-tools"
• "grunt", "grunt-cli"

package.steal.npmDependencies

Like npmIgnore but affirmative. If used alone will only include the dependencies listed. If used in conjunction with npmIgnore acts as an override. For example the following config:

{
  "dependencies": {
    "one": "1.0.0",
    "two": "1.0.0"
  },
  "steal": {
    "npmDependencies": [ "one" ]
  }
}

Will load one but ignore two.

When used in conjuction with npmIgnore:

{
  "devDependencies": {
    "one": "1.0.0",
    "two": "1.0.0",
    "three": "1.0.0"
  },
  "steal": {
    "npmIgnore": [ "devDependencies" ],
    "npmDependencies": [ "one" ]
  }
}

Even though npmIgnore is set to ignore all devDependencies the use of npmDependencies acts as an override. The package one will be loaded, but not two or three.

package.steal.npmAlgorithm

Used to determine which algorithm is used to look up packages.

The default algorithm is flat. We assume that you are using npm 3 or higher. See here more about the flat file structure of npm 3.

If you are using npm 2 or pnpm, your dependencies of node_modules will be nested. StealJS can handle the lookup by setting npmAlgorithm to nested.

{
  "steal": {
    "npmAlgorithm": "nested"
  }
}

package.steal.ignoreBrowser

Set to true to ignore browserfy's browser and browserify configurations.

{
  "steal": {
    "ignoreBrowser": true
  }
}

package.steal.directories

Set a folder to look for module's within your project. Only the lib directory can be specified.

In the following setup, my-project/my-utils will be looked for in my-project/src/my-utils.js:

{
  "name": "my-project"
  "steal": {
    "directories" : {
      "lib" : "src"
    }
  }
}

package.steal.configDependencies

Defines dependencies of your npm package. This is useful for loading modules, like extensions, that need to be initialized before the rest of your application is imported, e.g:

{
  "steal": {
    "configDependencies": [
      "./node_modules/steal-conditional/conditional"
    ]
  }
}

package.steal.plugins

Specifies packages that are used as plugins. These packages will be prefetched so that they're configuration will be applied before your app loads. An example is steal-css.

{
  "steal": {
    "plugins": ["steal-css"]
  }
}