5.3.6 • Public • Published


    node version webpack peer dependency version npm downloads

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


    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 ...


    data <string> (optional)

    Example: 'foo:bar,moo:goo'

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

    functions <string> (optional)

    Example: '/foo/bar/path'

    Locations of custom soy functions, usually a path to a *.jar file.

    expose <boolean> (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 <boolean> (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 Map<string, string | boolean> (optional)

    Example: { 'foo.bar.Template': 'foo/baz', 'moo.foo': false }

    To be used with the modularize option. 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 resolution handling.

    modulePathResolver : <Function> (optional)


    function customModulePathResolver(namespace, context) {
      return namespace.replace(/\./g, '/');
    function customModuleRelativePathResolver(namespace, context) {
      return path.relative(context, namespace.replace(/\./g, '/'));

    To be used with the modularize option. A function that takes a namespace [string], context [string], and outputs a module path when using modularize. You can read more about the value of context here: https://webpack.js.org/api/loaders/#thiscontext

    Returning an explicit false ignores a module and leaves it as a global reference. Return other falsy or undefined values to fallback to default resolution handling.


    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 = [
    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, the camelCase namespace becomes the kebab-case, dot separators become directories, and .soy suffix is appended.

    Example: The {namespace a.bCD} namespace is converted to import 'a/b-c-d.soy'; module path.

    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.

    Currently, the 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 the DEFAULT_MAPPINGS in the modular-soy.js file, and replace each false with a module name.

    Additional links

    Minimum requirements

    This plugin is compatible with:

    • webpack 4.0+ and 5.0+
    • Node 12+


    npm i @atlassian/soy-loader

    DownloadsWeekly Downloads






    Unpacked Size

    41.7 kB

    Total Files


    Last publish


    • kbielaski
    • dwalker
    • atlassian-aui
    • jvdl
    • mdejongh
    • mszczepanski
    • cdarroch
    • macku
    • dboyd
    • dmorrow
    • mstaas
    • cwhittington
    • doklovic
    • 1999-atlassian
    • amcculloch
    • wyasvoin
    • jmoynihan
    • xqiu
    • gleal-atlassian
    • mszpyra
    • bcytrowski
    • plai1
    • sraj
    • tilwin_atlassian
    • mrzymski
    • media-build-bot
    • akishore
    • timse
    • mkem114
    • tsebastian
    • sfp-release-bot