@atlassian/soy-loader

@atlassian/soy-loader

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

Installation

You can install the library using NPM:

npm install @atlassian/soy-loader

or by Yarn:

yarn add @atlassian/soy-loader

Usage example

// webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.soy/,
        use: [
          {
            loader: '@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.

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.

Recipes

Using with *.properties webpack loader

This package can be used with the @atlassian/i18n-properties-loader when you run your code with webpack dev server:

// webpack.config.js
const myI18nFiles = [
  'foo/i18n/my-translation-file.properties',
  'foo/bar/i18n/my-other-translation-file.properties',
  'bar/i18n/some-translation-file.properties',
];

module.exports = {
  module: {
    rules: [
      {
        test: /\.soy/,
        use: [
          {
            loader: '@atlassian/i18n-properties-loader',
            options: {
              i18nFiles: myI18nFiles,
            },
          },

          {
            loader: '@atlassian/soy-loader',
          },
        ],
      },
    ],
  },
};

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.

Additional links

• https://www.npmjs.com/package/@atlassian/i18n-properties-loader
• https://www.npmjs.com/package/@atlassian/wrm-react-i18n
• https://www.npmjs.com/package/atlassian-webresource-webpack-plugin

Minimum requirements

This plugin is compatible with:

• webpack 4.0+ and 5.0+
• Node 10+