@atlassian/atlassian-soy-loader

Atlassian Soy Loader

Compiles Soy Templates templates with @atlassian/soy-template-plugin-js package and allows to load them with webpack 3

Installation

You can install the library using NPM:

npm install @atlassian/atlassian-soy-loader

or by Yarn:

yarn add @atlassian/atlassian-soy-loader

Configure webpack 4

A configuration object looks like:

{
  module: {
    rules: [
      {
        test: /\.soy/,
        use: [{
          loader: '@atlassian/atlassian-soy-loader',
          options: {
              // ... see Options below ...
          }
        }]
      }
    ]
  }
}

Options

data : String (optional)

Example: 'foo:bar,moo:goo'

Data to pass to soy renderer (soy rendering only) in the form :,:

functions : String (optional)

Example: '/foo/bar/path'

Locations of custom soy functions, usually a jar.

i18n : String (optional)

Example: '/foo/bar/path/**/*.properties'

A glob for matching i18n properties files.

i18nBaseDir (optional)

Example: '/foo/bar/path'

The base directory for i18n properties files.

expose (optional)

Default: true

Indicates whether the generated namespace should be exposed to the window or not. If not, the module must be required to call the templates.

modularize (optional)

Default: false

Indicates whether to convert template calls and definitions to ES6 module imports and exports. Allows Webpack to track the chain of template calls, but assumes a naming convention that maps namespace strings to file paths. See [#Using-modularize](Using modularize) for details.

customModuleMap (optional)

Example: { 'foo.bar.Template': 'foo/baz' }

An object mapping namespaces to module names when using modularize. Explicit false ignores a module and leaves it as a global reference. Other falsy values fallback to default handling.

modulePathResolver (optional)

Example: namespace => namespace.replace(/\./g, '/')

A function that takes a namespace and outputs a module name when using modularize. Returning an explicit false ignores a module and leaves it as a global reference. Return other falsy values to fallback to default handling.

Using modularize

Modularize is a specialized case that can be used when your {namespace}s and Soy files are 1-to-1. It converts any external templates references to ES6 module imports (and conversely any defined templates become named exports from this module). This allows Webpack to trace dependencies between Soy files, rather than having to specify this manually.

By default camelCase becomes kebab-case, dot separators become directories, and '.soy' is appended. So {namespace a.bCD} becomes import 'a/b-c-d.soy';. This can be overridden using the customModuleMap option for one-off exceptions, and/or the modulePathResolver function to change the naming scheme entirely. NOTE: the modules MUST be unique per namespace (though a SMOP can improve this).

Currently AUI-provided namespaces are ignored and left as global variable references, and thus dependencies on AUI can't be tracked. If you want to handle this differently, check out DEFAULT_MAPPINGS modular-soy.js, and replace each false with a module name.

Changelog

3.0.0

• Added the modularize, customModuleMap and modulePathResolver options. Changed the dontExpose option to expose, but with the same default behavior.
• Updated dependency to Webpack 4. Webpack 3 might still work, but wasn't tested.
• Tested against Node v8.9.4 (but locally works against v10.10.0 too)

Contributors

Pull requests, issues and comments welcome. For pull requests:

• Add tests for new features and bug fixes
• Follow the existing style
• Separate unrelated changes into multiple pull requests

See the existing issues for things to start contributing.

For bigger changes, make sure you start a discussion first by creating an issue and explaining the intended change.

Atlassian requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership).

Prior to accepting your contributions we ask that you please follow the appropriate link below to digitally sign the CLA. The Corporate CLA is for those who are contributing as a member of an organization and the individual CLA is for those contributing as an individual.

• CLA for corporate contributors
• CLA for individuals

License

Copyright (c) 2017 Atlassian and others. Apache 2.0 licensed, see LICENSE file.