Less transformer removal

What is LESS transformer?

less-transformer was provided by less-transformer-plugin and has been used to compile .less web resources at runtime. It has been using LESS v1.7 running in Rhino (JS engine for the JVM).

LESS was a preferred way for writing styles for atlassian plugins for a long time as LESS tooling provided powerful utilities to organize and process styles. It also introduced the features that are no longer necessary with a global support for modern CSS features like variables, styles nesting and colour manipulation.

Removal from Platform

Timeline

We're removing both the LESS web-resource transformer and the LESS Maven plugin in all of our Data Center products in their next major versions: Jira Software 11, Jira Service Management 11, Confluence 10, Bitbucket 11, Bamboo 11 and Crowd by the end of 2025.

Styling plugins

We recommend you replace the runtime transformation of LESS files with build-time compilation or move to native CSS altogether where applicable.

Migration

You can either continue using LESS or switch entirely to native CSS. If your stylesheets heavily rely on LESS syntax or if your team has a preference for LESS follow migration to build-time compilation. Otherwise, if you want to remove LESS compilation entirely and switch to modern CSS, follow migration to CSS.

Migrating to build-time LESS compilation

File changes

1. Find all .less files in the plugin.

2. Remove all the imports with custom URI scheme (dynamic://, webstatic://, plugin://). Replace any global LESS variables with CSS variables - global variables. Remove any global LESS mixin usage.

3. Remove all custom LESS functions provided by less-transformer implementation: inlineimage, inlineimageunoptim, data-uri. Instead, you can reference the asset resource with url().

   1
   2
   + <resource type="download" name="images/logo.png" location="/images/logo.png" />
   Replace url in LESS/CSS stylesheet
   

   1
   2
   - background-image: inlineimage("images/logo.png");
   + background-image: url("images/logo.png");
   

4. Wrap any divisions in parentheses. less docs

   1
   2
   - margin-left: @section-gap / 2;
   + margin-left: (@section-gap / 2);
   

5. There might be other breaking changes between LESS v1.7 and latest LESS v4. You can verify the compilation outputs with online tools: LESS 1-3, LESS 4

Setting up LESS compilation

To compile the files we recommend using build tools like Webpack which supports LESS compilation with less-loader. Atlassian webpack plugin also makes it easy to integrate your plugin into Web Resource ecosystem.

If you are using Webpack 5, we recommend that you upgrade atlassian-webresource-webpack-plugin to at least 7.0.0, which doesn’t automatically add the less-transformer to web-resources.

Migrating LESS to CSS

File changes

1. Change .less file extensions to .css.

2. Replace all LESS variables with CSS variables. Prefix your CSS variables with the plugin name to avoid name clashes.

   1
   2
   - @color-pass: #8eb021;
   + .<plugin-name>-root-class {
   +   --<plugin-name>-color-pass: #8eb021;
   + }
   

   Media queries do not support CSS variables in their conditions.

3. Remove all mixins. The content of the mixin can be inlined where the mixin was used. Alternatively, you can transform the mixin into a separate CSS class and apply to HTML elements.

4. Remove use of any LESS function

   LESS function	CSS replacement
   desaturate(@color, 50%)	hsl(from var(--color) h max(0, calc(s - 50)) l)
   lighten(@color, 15%)	oklch(from var(--color) calc(l + 0.15) c h)
   darken(@color, 20%)	oklch(from var(--color) calc(l - 0.2) c h)
   @var1 + @var2	calc(var(--var-1) + var(--var-2)

5. Remove all imports and rely on defining web resource dependencies instead.

6. Update all comments to CSS syntax /* */

1
2
- // Comment in LESS
+ /* Comment in CSS */  

Setting up CSS minification

When using modern CSS features, you might find that the minifier provided in AMPS (yui-compressor) breaks certain style rules. There is multiple open issues in the project which is no longer actively maintained. We recommend using build tools like Webpack which supports CSS minification with modern tooling instead. Atlassian webpack plugin will make it easy to integrate your plugin into Web Resource ecosystem.

You can disable default CSS minification in amps-maven-plugin configuration.

1
2
<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>amps-maven-plugin</artifactId>
    <configuration>
        <compressCss>false</compressCss>
        <!-- ... -->
    </configuration>
</plugin>

Remove less-transformer

In pom.xml:

1. Remove any declarations and usages of lesscss-maven-plugin.

In atlassian-plugin.xml (or other web resource declaration files):

1. Remove all transformations with less-transformer or lessTransformer key

   1
   2
   - <transformation extension="less">
   -     <transformer key="less-transformer"/>
   - </transformation>
   

   1
   2
   - <transformation extension="less">
   -     <transformer key="lessTransformer"/>
   - </transformation>
   

2. Update resource locations in your atlassian-plugin.xml to point to .css files instead of .less files.

   1
   2
   - <resource type="download" name="page.less.css" location="page.less"/>
   + <resource type="download" name="page.css" location="page.css"/>
   

Testing and adoption

If the plugin uses any global variables from imports with dynamic:, webstatic: or plugin: URI scheme, and you want to replace them with global CSS variables, you will need to provide the global CSS variables values until they are available from products in EAP releases.

Any other changes are not blocked by products adoption and can be completed and tested against existing product versions.