Auto-generates web-resource definitions from your webpacked code, for usage in an Atlassian product or plugin.
npm install atlassian-webresource-webpack-pluginAuto-generates web-resource definitions from your webpacked code, for usage
in an Atlassian product or plugin.
[Atlassian's P2 plugin system][atlassian-p2] was shipped in 2008. At the time, the dependency management
system in P2 -- [the Web Resource Manager, or WRM][atlassian-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.
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
along with the appropriate
in the right order at a product's runtime.
This plugin supports and generates correct WRM output for the following webpack behaviours:
- a
- correct
- loading of non-JavaScript resources (via ExtractTextPlugin and friends).
Add this plugin to your webpack config. For every entry point webpack generates,
an appropriate
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:
``js
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 , and look something like this:
`xml
`
Also, 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 takencontext
automatically from the closest parent package.json of Webpack 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 theMETA-INF/plugin-descriptors directory as a value to an tag
in the section of the AMPS plugin's build configuration.
`xml`
You can see a demonstration P2 plugin using the webpack plugin here: [sao4fed-bundle-the-ui][101]
- 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
If you write your code using any of webpack's code-splitting techniques, such as calling require.ensure,
this plugin will automatically generate 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 :)
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 named after your entry-point.
For example, an entry point named "my-feature" will yield a web-resource like this:
`xml`
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, orcontextMap
- A 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.
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 entryprovidedDependencies
for the external in the configuration of this plugin. When your code isweb-resource
compiled, this plugin will automatically add an appropriate 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.
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 to your generated web-resource.
To include web-resources from exported by _this_ plugin you can use short notation like:
`js
// 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:
`js
// 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');
`
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 to your
generated web-resource:
`js
// 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.');
`
The Atlassian Web-Resource webpack Plugin has a number of configuration options.
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.
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.
Default is false.
When set to true, all generated web-resources will be added to
a context with the same name as the entrypoint.
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-
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.
An object specifying what conditions should be applied to a certain entry-point.
Simple example:
`json`
conditionMap: {
"my-first-entry-point": {
"class": "foo.bar"
},
}
will yield:
`xml`
Complex nested example with params:
`json`
conditionMap: {
"my-first-entry-point": {
"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:
`xml`
admin
project
admin
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:
`js
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:
`xml
`
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,plugin-key:web-resource
the value should either be in the format of , or be a reference to another entry-point in the same plugin.
`js
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:
`xml`
alternative="some.other.plugin:replacement-resource"
>
We moved all functionality to some.other.plugin
An object specifying transformations to be applied to file types.
The default transformations are:
- *.js files => jsI18n
- files => soyTransformer, jsI18n
Example configuration for custom transformations:
`json`
{
"transformationMap": {
"js": ["myOwnJsTransformer"],
"sass": ["myOwnSassTransformer"]
}
}
This would set the following transformations to every generated web-resource:
`xml`
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:
`js
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:
`json`
{
"transformationMap": false
}
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 tokey, name and state attributes of web-resource XML element. name and state properties are optional.
Mapping as follows:
`json`
{
"webresourceKeyMap": {
"firstWebResource": "first-web-resource",
"secondWebResource": {
"key": "second-web-resource",
"name": "Second WebResource",
"state": "disabled"
}
}
}
will result in the following web-resources:
`xml`
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:
`json5`
{
'dependency-name': {
dependency: 'atlassian.plugin.key:webresource-key',
import: {
// externals configuration
},
},
}
In this example, externals is a JSON object following the
[webpack externals format][webpack-externalobjects].
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 will be
added to the generated web-resource.
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.providedDependencies
This map is the exact same format that is accepted with the option above,providedDependencies
so one can use this map as a source for in another build:
`json`
{
"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 allowedoutput.libraryTarget
- must be set to amd
- More properties might be added to the WRM manifest file in future
#### Example configuration
`json`
{
"output": {
"library": "[name]",
"libraryTarget": "amd"
}
}
An object specifying additional parameters () for resources.
To specify for example content-types the server should respond with for a certain assets file-type (e.g. images/fonts):
`json`
{
"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_
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.
Uses provided value (instead of DEV_PSEUDO_HASH) in the webresource name that contains all of the assets needed in development mode.
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.
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.
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.
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.
Indicate verbosity of log output. Default is false.
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)][atlassian-amps] 6.2.11+
- [Atlassian Web Resource Manager (WRM)][atlassian-wrm] 4.3.6+
This plugin is tested with webpack 5.0+.
- To compile CSS, use css-loader >= 5 along with mini-css-extract-plugin >= 2.mini-css-extract-plugin
- When using 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.
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:
`shell`
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][wrm-troubleshooting].
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 (
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 (
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),
`
A solution is to downgrade to webpack-sources@2`
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][issuetracker].
Our development team review all open issues and triage on a monthly basis.
[101]: https://bitbucket.org/serverecosystem/sao4fed-bundle-the-ui
[atlassian-sdk]: https://developer.atlassian.com/server/framework/atlassian-sdk
[atlassian-amps]: https://developer.atlassian.com/server/framework/atlassian-sdk/working-with-maven/#using-the-amps-maven-plugin-directly
[atlassian-p2]: https://bitbucket.org/atlassian/atlassian-plugins
[atlassian-wrm]: https://bitbucket.org/atlassian/atlassian-plugins-webresource
[webpack]: https://webpack.js.org/
[webpack-externalobjects]: https://webpack.js.org/configuration/externals/#object
[issuetracker]: https://ecosystem.atlassian.net/jira/software/c/projects/SPFE/issues/
[wrm-troubleshooting]: https://www.npmjs.com/package/@atlassian/wrm-troubleshooting