server

Configuration

The recommended configuration method is a .modulerc.js file in your project's root directory.

Property	Type	Default	Description
root	{string}	'.'	The project root
entry	{string}	'.'	The project entrypoint
output	{string}	'.remote'	The output directory
env	{string}	See env	The target build environment
watch	{boolean}	false	Watch source files and rebuild on change
preset	{string}	See preset	Applies a predefined set of options
strict	{boolean}	false	Fail on missing dependency
define	{Object}	See define	An object containing expressions to be evaluated by the compiler
provide	{Object}	{}	An object containing variable or import references to be injected by the compiler as needed
extensions	{string[]}	See extensions	File extensions searched by the resolver
mainFields	{string[]}	['module', 'main']	Package fields searched by the resolver
moduleDirs	{string[]}	['node_modules']	Module directories searched by the resolver
middleware	{Middleware[]}	See middleware	An array of objects that can modify resource requests and output
adapters	{Object[]}	See adapters	An array of objects that handle parsing and transforming different file types
optimize	{boolean|Object}	See optimize	A boolean or object controlling which optimization transforms are applied during compilation
babel	{Object}	See babel	Options passed to @babel/core
babylon	{Object}	See babylon	Options passed to @babel/parser
uglify	{Object|boolean}	See uglify	Options passed to uglify-es
server	{Object}	See server	Server configuration
sourceMaps	{string|boolean}	See sourceMaps	Source map configuration
include	{string[]}	[]	An array of glob patterns for resources to be included with all import requests
outputTarget	{string}	'module'	The module wrapper template
core	{Object}	browserify/resolve/lib/core.json	An object that defines core modules

env

process.env.BUILD_ENV || process.env.NODE_ENV || 'development'

preset

• browser

  {
    mainFields: ['browser'],
    define: {
      'process.browser': true,
      'typeof window': 'object',
      'typeof document': 'object',
      'typeof XMLHttpRequest': 'function'
    },
    provide: {
      global: 'window',
      process: `import process from '${ConfigStore.shims.process}'`,
      Buffer: `import { Buffer } from '${ConfigStore.mocks.buffer}'`
    },
    middleware: [
      // Rewrite requests for node core modules to browser shims
      RewriteMiddleware(
        new RegExp(
          `^(${Object.keys(ConfigStore.shims)
            .map(escapeRegExp)
            .join('|')})$`
        ),
        ctx => ConfigStore.shims[ctx.request]
      )
    ]
  }

• node

  {
    define: {
      'process.browser': false,
      'typeof window': 'undefined',
      'typeof document': 'undefined',
      'typeof XMLHttpRequest': 'undefined'
    }
  }

define

{
  'process.env.NODE_ENV': define['process.env.BUILD_ENV'] || env,
  'typeof process': 'object'
}

extensions

['.js', '.jsx', '.mjs', '.es', '.es6', '.json']

middleware

[
  // Treat absolute URIs as external resources
  ExternalMiddleware(ctx => isAbsoluteURL(ctx.request)),
  // Treat data URIs as external resources
  ExternalMiddleware(/^data:\w+/i)
]

There are two types of middleware: ContextMiddleware Runs before the resource is created and is used to modify SourceContext. ResourceMiddleware Runs after the resource is created and is used to modify NormalResource.

• ContextMiddleware

  Generic context middleware. Does nothing on its own, but can be used to perform custom operations on ctx.

  ContextMiddleware(
    test?: RegExp | (ctx: SourceContext) => boolean,
    apply: (ctx: SourceContext) => void
  )

• ExternalMiddleware (type: context)

  Flags a resource request as external. Requests for external resources are left unmodified by the compiler, are not added to the module manifest, and are loaded using client.externalRequire when applicable.

  ExternalMiddleware(test: RegExp | (ctx: SourceContext) => boolean)

• RewriteMiddleware (type: context)

  Rewrites a resource request to the returned value.

  RewriteMiddleware(
    test?: RegExp | (ctx: SourceContext) => boolean,
    apply: (ctx: SourceContext) => string
  )

• NullMiddleware (type: context)

  Rewrites a resource request to null.

  NullMiddleware(test: RegExp | (ctx: SourceContext) => boolean)

• ResourceMiddleware

  Generic resource middleware. Does nothing on its own, but can be used to perform custom operations on resource.

  ResourceMiddleware(
    test?: RegExp | (resource: NormalResource, ctx: SourceContext) => boolean,
    apply: (resource: NormalResource, ctx: SourceContext) => void
  )

• UnionMiddleware (type: resource)

  Groups matched resources based on certain criteria (template, resource.async, resource.adapter.outputType) and combines their output based on the values of minSize and maxSize. Can reduce the total number of HTTP requests per import by combining many small modules into a few larger assets.

  template can be used to customize the way resources are grouped. It can contain interpolation placeholders that will be replaced with resource properties (i.e. template: '{packageId}' would only combine resources with the same packageId).

  UnionMiddleware doesn't always play nice with the watch option, so it's best not to use them together on resources that will be changing.

  UnionMiddleware(options?: {
    minSize?: number = 5e4,
    maxSize?: number = 10e4,
    template?: string,
    test?: (resource: NormalResource, ctx: SourceContext) => boolean
  })

  Example

  // Combine all @babel/runtime or core-js modules into a single asset for each package
  UnionMiddleware({
    maxSize: Infinity,
    template: '{packageId}',
    test: ({ packageId }) => packageId === '@babel/runtime' || packageId === 'core-js'
  })
  
  // Combine all node_modules into assets between 50 kB and 100 kB
  UnionMiddleware({
    test: resource => resource.packageId !== '.'
  })

adapters

[
  {
    test: ctx => ctx.extension === '.css',
    adapter: CSSAdapter
  },
  {
    test: ctx => ctx.extension === '.less',
    adapter: LESSAdapter
  },
  {
    test: ctx => ctx.extension === '.sass' || ctx.extension === '.scss',
    adapter: SASSAdapter
  },
  {
    test: ctx => ctx.extension === '.json',
    adapter: JSONAdapter
  },
  {
    test: ctx => defaultExtensions.includes(ctx.extension),
    adapter: ScriptAdapter
  }
]

There's not much to say about adapters - the API is going to be overhauled with the next major release, so it's unlikely support for additional file types will be added before then. Customize at your own risk!

If no matching adapter is found, the resource is left unchanged.

optimize

{
  constantFolding: env === 'production',
  deadCode: true,
  unreferenced: true
}

• constantFolding: Applies babel-plugin-minify-constant-folding
• deadCode: Applies babel-plugin-minify-dead-code-elimination
• unreferenced: Applies unreferenced identifier transform

babel

{
  envName: process.env.BABEL_ENV || env
}

Accepts any options supported by @babel/core

babylon

{
  sourceType: 'module',
  plugins: [
    'asyncGenerators',
    'classProperties',
    'dynamicImport',
    'exportDefaultFrom',
    'exportNamespaceFrom',
    'jsx',
    'objectRestSpread'
  ]
}

Accepts any options supported by @babel/parser

uglify

{
  compress: {
    // https://github.com/mishoo/UglifyJS2/issues/2874
    inline: false
  },
  output: {
    comments: false
  }
}

Accepts any options supported by uglify-es

server

{
  port: 3000,
  uri: 'http://localhost:3000',
  publicPath: Url.parse(server.uri).pathname,
  redirects: env === 'development'
}

• port: The server's internal port
• uri: The full, public server uri, i.e. https://mydomain.io/modules/foo
• redirects: Enables canonical URL redirects, i.e. /@default => /@default/_/index.js

sourceMaps

env === 'production' ? true : 'inline'

• inline: Generate and append base64-encoded source maps
• hidden: Generate external source maps but don't append the URLs
• true: Generate external source maps and append the URLs
• false: Don't generate source maps

^{NOTE: sourceMaps cannot be combined with UnionMiddleware. See #26.}

SourceContext

SourceContext {
  async: boolean,
  error: Error | null,
  extension: string | null,
  force?: string,
  moduleId: string,
  origin: string,
  packageId: string | null,
  pid: number,
  request: string,
  resolved: string | null,
  slug: string | null,
  url: string,
  isExternal: () => boolean,
  isNull: () => boolean
}

NormalResource

NormalResource {
  async: boolean,
  error: Error | null,
  moduleId: string,
  origin: string,
  packageId: string | null,
  pid: number,
  slug: string | null,
  url: string,
  isExternal: () => boolean,
  isNull: () => boolean
}

Server

new Server([options]) ⇒ Server

Param	Type	Description
[options]	{Object}	Any options listed in the Configuration section

server.install([force]) ⇒ Promise<NormalResource>

Param	Type	Default	Description
[force]	{boolean}	false	Force a fresh install

server.listen([port]) ⇒ Promise<void>

Param	Type	Default	Description
[port]	{number}	server.port	The server port

server.close() ⇒ Promise<void>