Atlassian Web-Resource webpack Plugin

Auto-generates web-resource definitions from your webpacked code, for usage in an Atlassian product or plugin.

Why?

Atlassian's P2 plugin system was shipped in 2008. At the time, the dependency management system in P2 -- the Web Resource Manager, or WRM -- was a godsend for managing the growing complexity of the front-end resources. It offered, amongst other things:

• The ability to specify bundles of related resources, called a "web-resource".
• The ability to specify inter-dependencies of web-resources, so that
• Batching of necessary code in production could be achieved, and
• Source order could be maintained.

Fast-forward to 2017, and front-end development is drastically different from it was back then. JavaScript module systems and webpack have solved many of the problems the WRM initially set out to.

Unfortunately, Atlassian's plugin system doesn't speak webpack. Happily, though, we can teach webpack to speak Atlassian-Plugin. That's what this plugin does.

What does it do?

When you add this plugin to your webpack configuration, it will generate an XML file with the various WRM configuration necessary to make your code run in an Atlassian product.

You will be able to write your plugin's front-end code using any JavaScript module system. This plugin will figure out how to turn all of it in to the correct <web-resource> declarations, along with the appropriate <dependency> declarations so that your code ends up loading in the right order at a product's runtime.

This plugin supports and generates correct WRM output for the following webpack behaviours:

• a <web-resource> per webpack entry point
• correct <web-resource>s for code-splitting / loading asynchronous chunks
• loading of non-JavaScript resources (via ExtractTextPlugin and friends).

How to use the plugin

Basic setup

Add this plugin to your webpack config. For every entry point webpack generates, an appropriate <web-resource> definition will be generated in an XML file for you, which can then be bundled in to your Atlassian product or plugin, ready to be served to the browser at product runtime.

Given this webpack config:

const WrmPlugin = require('atlassian-webresource-webpack-plugin');

module.exports = {
  entry: {
    'my-feature': path.join(FRONTEND_SRC_DIR, 'simple.js'),
  },
  plugins: [
    new WrmPlugin({
      pluginKey: 'my.full.plugin.artifact-id',
      contextMap: {
        'my-feature': ['atl.general'],
      },
      xmlDescriptors: path.resolve(OUTPUT_DIR, 'META-INF', 'plugin-descriptors', 'wr-defs.xml'),
    }),
  ],
  output: {
    filename: 'bundled.[name].js',
    path: path.resolve(OUTPUT_DIR),
  },
};

The output will go to <OUTPUT_DIR>/META-INF/plugin-descriptors/wr-defs.xml, and look something like this:

<bundles>

        <web-resource key="entrypoint-my-feature">
            <transformation extension="js">
                <transformer key="jsI18n"/>
            </transformation>
            <context>atl.general</context>
            <resource name="bundled.my-feature.js" type="download" location="bundled.my-feature.js" />
        </web-resource>

</bundles>

Also, <OUTPUT_DIR>/META-INF/fe-manifest-associations/ will include list of resources created by this webpack build and NPM package name for AMPs resource association feature.

Package name can be specified by passing packageName field to WrmPlugin directly, otherwise it is taken automatically from the closest parent package.json of Webpack context directory.

Association is automatically detected by AMPs in P2 plugins and is expected to be in target/classes/META-INF/fe-manifest-associations of plugin build.

Consuming the output in your P2 plugin

In your P2 plugin project's pom.xml file, add the META-INF/plugin-descriptors directory as a value to an <Atlassian-Scan-Folders> tag in the <instruction> section of the AMPS plugin's build configuration.

<build>
  <plugins>
    <plugin>
      <!-- START of a bunch of stuff that is probably different for your plugin, but is outside
           the scope of this demonstration -->
      <groupId>com.atlassian.maven.plugins</groupId>
      <artifactId>maven-amps-plugin</artifactId>
      <version>6.2.11</version>
      <!-- END differences with your plugin -->
      <configuration>
        <instructions>
          <Atlassian-Scan-Folders>META-INF/plugin-descriptors</Atlassian-Scan-Folders>
        </instructions>
      </configuration>
    </plugin>
  </plugins>
</build>

Demonstration P2 plugin usage

You can see a demonstration P2 plugin using the webpack plugin here: sao4fed-bundle-the-ui

• Watch this AtlasCamp 2018 talk which uses this plugin amongst others to make your devloop super fast: https://youtu.be/VamdjcJCc0Y
• Watch this AtlasCamp 2017 talk about how to build and integrate your own front-end devtooling on top of P2, which introduced the alpha version of this plugin: https://youtu.be/2yf-TzKerVQ?t=537

Features

Code splitting

If you write your code using any of webpack's code-splitting techniques, such as calling require.ensure, this plugin will automatically generate <web-resource> definitions for them, and automatically translate them in to the appropriate calls to load them asynchronously at an Atlassian product's runtime.

In other words, there's practically no effort on your part to make your critical path small :)

Flexible generation of web-resource definitions

By default, a generated web-resource will have:

• A key based on the name of your webpack entry-point, and
• Will be included in a <context> named after your entry-point.

For example, an entry point named "my-feature" will yield a web-resource like this:

<web-resource key="entrypoint-my-feature">
  <context>my-feature</context>
  <!-- the resources for your entry-point -->
</web-resource>

For new code, this should be enough to get your feature loading in to a place you want it to in your plugin or product -- assuming the appropriate call on the server-side is made to include your web-resource.

Sometimes, in order to ensure your code loads when it's expected to, you will need to override the values generated for you. To do this, when defining the WrmPlugin's config, you can provide either:

• A webresourceKeyMap to change the web-resource's key or name to whatever you need it to be, or
• A contextMap to include the web-resource in any number of web-resource contexts you expect it to load in to.

It's most likely that you'll want to specify additional contexts for a web-resource to load in to. When all of your web-resources are automatically generated and loaded via contexts, there is no need to know its key. You would typically provide your own web-resource key when refactoring old code to webpack, in order to keep the dependencies working in any pre-existing code.

Module-mapping to web-resources

If you use a common library or module -- for example, 'jquery' or 'backbone' -- and you know that this module is provided by a P2 plugin in the product's runtime, you can map your usage of the module to the web-resource that provides it.

All you need to do is declare the appropriate webpack external for your module, and add an entry for the external in the providedDependencies configuration of this plugin. When your code is compiled, this plugin will automatically add an appropriate web-resource dependency that will guarantee your code loads after its dependants, and will prevent your bundle from getting too large.

For details, check the providedDependencies section in the configuration section.

Legacy web-resource inclusion

90% of the time, your JavaScript code should be declaring explicit dependencies on other modules. In the remaining 10% of cases, you may need to lean on the WRM at runtime to ensure your code loads in the right order. 9% of the time, the module-mapping feature should be enough for you. In the remaining 1%, you may just need to add a web-resource dependency to force the ordering.

You can add import statements to your code that will add a <dependency> to your generated web-resource.

To include web-resources from exported by this plugin you can use short notation like:

// in AMD syntax
define(function (require) {
  require('wr-dependency!my-webresource');
  console.log('my-webresource will have been loaded synchronously with the page');
});

// in ES6
import 'wr-dependency!my-webresource';

console.log('my-webresource will have been loaded synchronously with the page');

To include resources exported by other plugins, provide full plugin key:

// in AMD syntax
define(function (require) {
  require('wr-dependency!com.atlassian.auiplugin:dialog2');
  console.log('webresource will have been loaded synchronously with the page');
});

// in ES6 syntax
import 'wr-dependency!com.atlassian.auiplugin:dialog2';

console.log('webresource will have been loaded synchronously with the page');

Legacy runtime resource inclusion

95% of the time, your application's non-JavaScript resources -- CSS, images, templates, etc. -- are possible to bundle and include via webpack loaders. Sometimes, though, you will have resources that only work during an Atlassian product's runtime -- think things like Atlassian Soy templates and a product's Less files for look-and-feel styles -- and it isn't possible to make them work during ahead-of-time compilation.

In these cases, you can add import statements to your code that will add a <resource> to your generated web-resource:

// in AMD syntax
define(function (require) {
  require('wr-resource!my-runtime-styles.css!path/to/the/styles.less');
  require('wr-resource!my-compiled-templates.js!path/to/the/templates.soy');

  console.log('these styles and templates will be transformed to CSS and JS at product runtime.');
});

// in ES6 syntax
import 'wr-resource!my-runtime-styles.css!path/to/the/styles.less';
import 'wr-resource!my-compiled-templates.js!path/to/the/templates.soy';

console.log('these styles and templates will be transformed to CSS and JS at product runtime.');

Configuring the plugin

The Atlassian Web-Resource webpack Plugin has a number of configuration options.

pluginKey (Required)

The fully-qualified groupId and artifactId of your P2 plugin. Due to the way the WRM works, this value is necessary to provide in order to support loading of asynchronous chunks, as well as arbitrary (non-JavaScript) resources.

xmlDescriptors (Required)

An absolute filepath to where the generated XML should be output to. This should point to a sub-directory of the Maven project's ${project.build.outputDirectory} (which evaluates to target/classes in a standard Maven project).

The sub-directory part of this configuration value needs to be configured in the project's pom.xml, as demonstrated in the basic usage section above.

addEntrypointNameAsContext (Optional)

Default is false.

When set to true, all generated web-resources will be added to a context with the same name as the entrypoint.

addAsyncNameAsContext (Optional)

Default is false.

When set to true, all generated web-resources for async chunks that have a name (specified via webpackChunkName on import) will be added to a context of the name "async-chunk-".

contextMap (Optional)

A set of key-value pairs that allows you to specify which webpack entry-points should be present in what web-resource contexts at an Atlassian product runtime.

You can provide either a single web-resource context as a string, or an array of context strings.

conditionMap (Optional)

An object specifying what conditions should be applied to a certain entry-point. Simple example:

{
  "class": "foo.bar"
}

will yield:

<condition class="foo.bar" />

Complex nested example with params:

{
  "conditionMap": {
    "type": "AND",
    "conditions": [
      {
        "type": "OR",
        "conditions": [
          {
            "class": "foo.bar.baz",
            "invert": true,
            "params": [
              {
                "attributes": {
                  "name": "permission"
                },
                "value": "admin"
              }
            ]
          },
          {
            "class": "foo.bar.baz2",
            "params": [
              {
                "attributes": {
                  "name": "permission"
                },
                "value": "project"
              }
            ]
          }
        ]
      },
      {
        "class": "foo.bar.baz3",
        "params": [
          {
            "attributes": {
              "name": "permission"
            },
            "value": "admin"
          }
        ]
      }
    ]
  }
}

will yield:

<conditions type="AND">
  <conditions type="OR">
    <condition class="foo.bar.baz" invert="true">
      <param name="permission">admin</param>
    </condition>
    <condition class="foo.bar.baz2" >
      <param name="permission">project</param>
    </condition>
  </conditions>
  <condition class="foo.bar.baz3" >
    <param name="permission">admin</param>
  </condition>
</conditions>

dataProvidersMap (Optional)

The dataProvidersMap option allows configuring the association between entrypoint and a list of data providers.

Data providers can be used to provide a data from the server-side to the frontend, and claimed using WRM.data.claim API. To read more about data providers refer to the official documentation.

To associate the entrypoint with list of data providers you can configure the webpack configuration as follow:

module.exports = {
  entrypoints: {
    'my-first-entry-point': './first-entry-point.js',
    'my-second-entry-point': './first-entry-point.js',
  },

  plugins: [
    WrmPlugin({
      pluginKey: 'my.full.plugin.artifact-id',
      dataProvidersMap: {
        'my-first-entry-point': [
          {
            key: 'my-foo-data-provider',
            class: 'com.example.myplugin.FooDataProvider',
          },
        ],

        'my-second-entry-point': [
          {
            key: 'my-bar-data-provider',
            class: 'com.example.myplugin.BarDataProvider',
          },

          {
            key: 'my-bizbaz-data-provider',
            class: 'com.example.myplugin.BizBazDataProvider',
          },
        ],
      },
    }),
  ],
};

will yield:

<atlassian-plugin>
    <web-resource key="<<key-of-my-first-entry-point>>">
        <resource  />
        <resource  />

        <data key="my-foo-data-provider" class="com.example.myplugin.FooDataProvider" />
    </web-resource>

    <web-resource key="<<key-of-my-first-entry-point>>">
        <resource  />
        <resource  />

        <data key="my-bar-data-provider" class="com.example.myplugin.BarDataProvider" />
        <data key="my-bizbaz-data-provider" class="com.example.myplugin.BizBazDataProvider" />
    </web-resource>
</atlassian-plugin>

deprecatedEntrypoints (Optional)

An object specifying which entry-points should be marked as being deprecated.

A true value may be used instead to simply mark an entry-point as being deprecated without providing any additional information.

Otherwise an object may be used to provide additional context as to when and why the entry-point was deprecated. For the alternative key, the value should either be in the format of plugin-key:web-resource, or be a reference to another entry-point in the same plugin.

module.exports = {
  entrypoints: {
    'my-first-entry-point': './first-entry-point.js',
    'my-second-entry-point': './second-entry-point.js',
    'my-third-entry-point': './third-entry-point.js',
  },

  plugins: [
    WrmPlugin({
      pluginKey: 'my.full.plugin.artifact-id',
      deprecatedEntrypoints: {
        'my-first-entry-point': true,
        'my-second-entry-point': {
          sinceVersion: '3.0',
          removeInVersion: '4.0',
          // alternative could also reference another entrypoint i.e. 'my-third-entry-point'
          alternative: 'some.other.plugin:replacement-resource',
          extraInfo: 'We moved all functionality to some.other.plugin',
        },
      },
    }),
  ],
};

will yield:

<atlassian-plugin>
    <web-resource key="entrypoint-my-first-entry-point">
        <!-- ... rest of definition ... -->
        <deprecated />
    </web-resource>
    <web-resource key="entrypoint-my-second-entry-point">
        <!-- ... rest of definition ... -->
        <deprecated since="3.0"
                    remove="4.0"
                    alternative="some.other.plugin:replacement-resource"
        >
            We moved all functionality to some.other.plugin
        </deprecated>
    </web-resource>
</atlassian-plugin>

transformationMap (Optional)

An object specifying transformations to be applied to file types. The default transformations are:

• *.js files => jsI18n
• *.soy files => soyTransformer, jsI18n

Example configuration for custom transformations:

{
  "transformationMap": {
    "js": ["myOwnJsTransformer"],
    "sass": ["myOwnSassTransformer"]
  }
}

This would set the following transformations to every generated web-resource:

<web-resource key="...">
    <transformation extension="js">
      <transformer key="myOwnJsTransformer"/>
    </transformation>
    <transformation extension="sass">
      <transformer key="myOwnSassTransformer"/>
    </transformation>
</web-resource>

If you wish to extend the default transformations you can use the build-in extendTransformations function provided by the plugin. It will merge the default transformations with your custom config:

const WrmPlugin = require('atlassian-webresource-webpack-plugin');

new WrmPlugin({
  pluginKey: 'my.full.plugin.artifact-id',
  transformationMap: WrmPlugin.extendTransformations({
    js: ['myOwnJsTransformer'],
    sass: ['myOwnSassTransformer'],
  }),
});

You can also completely disable the transformations by passing false value to the plugin configuration:

{
  "transformationMap": false
}

webresourceKeyMap (Optional)

Allows you to change the name of the web-resource that is generated for a given webpack entry-point.

This is useful when you expect other plugins will need to depend on your auto-generated web-resources directly, such as when you refactor an existing feature (and its web-resource) to be generated via webpack.

This parameter can take either string or object with properties key, name and state which corresponds to key, name and state attributes of web-resource XML element. name and state properties are optional.

Mapping as follows:

{
  "webresourceKeyMap": {
    "firstWebResource": "first-web-resource",
    "secondWebResource": {
      "key": "second-web-resource",
      "name": "Second WebResource",
      "state": "disabled"
    }
  }
}

will result in the following web-resources:

<atlassian-plugin>
<web-resource key="first-web-resource" name="" state="enabled">
  <!-- your resources definitions -->
</web-resource>
<web-resource key="second-web-resource" name="Second WebResource" state="disabled">
  <!-- your resources definitions -->
</web-resource>
</atlassian-plugin>

providedDependencies (Optional)

A map of objects that let you associate what web-resources house particular external JS dependencies.

The format of an external dependency mapping is as follows:

{
  'dependency-name': {
    dependency: 'atlassian.plugin.key:webresource-key',
    import: {
      // externals configuration
    },
  },
}

In this example, externals is a JSON object following the webpack externals format.

When your code is compiled through webpack, any occurrence of dependency-name found in a module import statement will be replaced in the webpack output, and an appropriate web-resource <dependency> will be added to the generated web-resource.

wrmManifestPath (Optional)

A path to a WRM manifest file where the plugin will store a map of objects. Under the providedDependencies property is a map of dependencies, including the generated web-resource keys. This map is the exact same format that is accepted with the providedDependencies option above, so one can use this map as a source for providedDependencies in another build:

{
  "providedDependencies": {
    "dependency-name": {
      "dependency": "atlassian.plugin.key:webresource-key",
      "import": {
        "var": "require('dependency-amd-module-name')",
        "amd": "dependency-amd-module-name"
      }
    }
  }
}

Notes and limitations

• Both output.library and output.libraryTarget must be set for the WRM manifest file to be created.
• output.library must not contain [chunk] or [hash], however [name] is allowed
• output.libraryTarget must be set to amd
• More properties might be added to the WRM manifest file in future

Example configuration

{
  "output": {
    "library": "[name]",
    "libraryTarget": "amd"
  }
}

resourceParamMap (Optional)

An object specifying additional parameters (<param/>) for resources.

To specify for example content-types the server should respond with for a certain assets file-type (e.g. images/fonts):

{
  "resourceParamMap": {
    "svg": [
      {
        "name": "content-type",
        "value": "image/svg+xml"
      }
    ]
  }
}

Setting specific content-types may be required by certain Atlassian products depending on the file-type to load. Contains content-type for svg as "image/svg+xml" by default

locationPrefix (Optional)

Adds given prefix value to location attribute of resource node. Use this option when your webpack output is placed in a subdirectory of the plugin's ultimate root folder.

devAssetsHash (Optional)

Uses provided value (instead of DEV_PSEUDO_HASH) in the webresource name that contains all of the assets needed in development mode.

watch and watchPrepare (Optional)

Activates "watch-mode". This must be run in conjunction with a webpack-dev-server.

watchPrepare

Creates "proxy"-Resources and references them in the XML-descriptor. These proxy-resources will redirect to a webpack-dev-server that has to be run too. In order for this to work properly, ensure that the webpack-config "options.output.publicPath" points to the webpack-dev-server - including its port. (e.g. http://localhost:9000)

watch (Optional)

Use when running the process with a webpack-dev-server.

useDocumentWriteInWatchMode (Optional)

When set to true, the generated watch mode modules will add the script tags to the document synchronously with document.write while the document is loading, rather than always relying on asynchronously appended script tags (default behaviour).

This is useful when bundles are expected to be available on the page early, e.g. when code in a template relies on javascript to be loaded blockingly.

noWRM (Optional)

Will not add any WRM-specifics to the webpack-runtime or try to redirect async-chunk requests while still handling requests to wr-dependency and wr-resource. This can be useful to develop frontend outside of a running product that provides the WRM functionality.

singleRuntimeWebResourceKey (Optional)

Set a specific web-resource key for the webpack runtime when using the webpack option optimization.runtimeChunk to single (see runtimeChunk documentation). Default is common-runtime.

verbose (Optional)

Indicate verbosity of log output. Default is false.

Minimum requirements

This plugin has been built to work with the following versions of the external build tools:

• Node 18 (at P2 plugin build-time)
• Atlassian Maven Plugin Suite (AMPS) 6.2.11+
• Atlassian Web Resource Manager (WRM) 4.3.6+

This plugin is tested with webpack 5.0+.

Recommended with webpack 5

• To compile CSS, use css-loader >= 5 along with mini-css-extract-plugin >= 2.
• When using mini-css-extract-plugin runtime option needs to be set to false. This will prevent mini-css-extract-plugin from injecting extracted css to document head, which is done by WRM.

Upgrade guides

• Upgrade to 7.0.0

Troubleshooting and known problems

Self troubleshooting tool

We provide a tool that helps troubleshoot the configuration of webpack and Atlassian P2 projects.

To check if your project was configured correctly, open a terminal and navigate to the root directory of your project. Next, run the troubleshooting command:

npx @atlassian/wrm-troubleshooting

The tool will ask you a few questions and guide you if it finds issues with your projects' configuration.

You can read more about the troubleshooting tool on the NPM page for the @atlassian/wrm-troubleshooting package.

webpack-sources compatibility

If you install webpack-sources@3 along with webpack@4, you'll likely get this error:

/project/path/node_modules/webpack/node_modules/webpack-sources/lib/ConcatSource.js:59
                        return typeof item === "string" ? item : item.node(options);

TypeError: item.node is not a function
    at /project/path/node_modules/webpack/node_modules/webpack-sources/lib/ConcatSource.js:59:50
    at Array.map (<anonymous>)
    at ConcatSource.node (/project/path/node_modules/webpack/node_modules/webpack-sources/lib/ConcatSource.js:58:63)
    at proto.sourceAndMap (/project/path/node_modules/webpack/node_modules/webpack-sources/lib/SourceAndMapMixin.js:29:18)
    at CachedSource.sourceAndMap (/project/path/node_modules/webpack/node_modules/webpack-sources/lib/CachedSource.js:58:31)
    at getTaskForFile (/project/path/node_modules/webpack/lib/SourceMapDevToolPlugin.js:65:30)
    at /project/path/node_modules/webpack/lib/SourceMapDevToolPlugin.js:215:20
    at Array.forEach (<anonymous>)
    at /project/path/node_modules/webpack/lib/SourceMapDevToolPlugin.js:186:12
    at SyncHook.eval [as call] (eval at create (/project/path/node_modules/webpack/node_modules/tapable/lib/HookCodeFactory.js:19:10), <anonymous>:7:1)

A solution is to downgrade to webpack-sources@2

Other problems

Check that your build and bundle works as you expect without this plugin enabled. You can disable the WRM webpack plugin and bundle the code to verify no errors or warnings are present in the webpack output.

This plugin makes very few changes to what webpack ultimately outputs. If your bundles have content errors, it may be due to version incompatibilities between webpack and the loader plugins in your build configuration.

Known problems with this plugin are listed in the Atlassian Ecosystem issue tracker. Our development team review all open issues and triage on a monthly basis.