Javascript Modules Engine

supported

Télécharger 1.2.0

Informations

Identifiant du module

javascript-modules-engine

Identifiant de groupe

org.jahia.modules

Statut

supported

Catégorie

Platform

Auteur

JSG

Site web du développeur

http://www.jahia.com

Nécessite Jahia

8.2.1.0

Mis à jour

2026-07-09

Source

scm:git:git@github.com:Jahia/javascript-modules.git/javascript-modules-engine

Étiquettes

react
frontend
headless

This is the engine allowing JavaScript modules to run on a Jahia server.

Note: This module was previously called NPM modules engine. Javascript Modules 0.3.0 is a continuation of work done in NPM Modules Engine v0.5.0 which is now deprecated.

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.

"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:

(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and

(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and

(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and

(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.

You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

APPENDIX: How to apply the Apache License to your work.

To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Versions

1.2.0Télécharger

Improvements

Generate OSGi capabilities from declared nodetypes in cnd and xml import files

Misc

Removed warning about JDK not supporting runtime compilation

1.1.0Télécharger

New Features

useGQLQuery now accepts an optionally typed GraphQL document for its query parameter. (#548)

This enables compatibility with GraphQL libraries such as gql.tada and GraphQL Codegen.
Enabled buildNodeUrl support for Java decorators by using the underlying node.getUrl() Java implementation. (#549)

Example: buildNodeUrl(imageNode, { args: { width: 640 } }) will execute imageNode.getUrl(['width:640']).
Enabled jahia-deploy support for custom context in the JAHIA_HOST env var. (#551)
Improved the type declaration of <Render> to prevent runtime errors. (#571)

We have not changed the implementation of <Render>, only its type declaration. If you encounter red squiggles on <Render>, your code will behave exactly the same as before, but it might mean you use mutually exclusive parameters, and one of them is ignored, or that you are missing a required parameter that gets a temporary value at runtime.

Other Changes

GraalVM runtime libraries (the Java code that runs JavaScript code) are now embedded in the JavaScript Modules Engine instead of Jahia core. (#601, #609, #610)

This does not change anything if you are using JavaScript Modules, but makes the core slightly lighter for Java-only Jahia stacks.

This change is coordinated with the upcoming release of Jahia 8.2.3.0: future versions of Jahia will require the JavaScript Modules Engine in version 1.1.0 or greater for JavaScript Modules to work.

All embedded libraries were upgraded to their latest version:

Library	Version in JSM 1.0.1	Version in JSM 1.1.0
`react`	19.2.0	19.2.3
`react-dom`	19.2.0	19.2.3
`i18next`	25.6.0	25.7.3
`react-i18next`	16.1.0	16.5.0

To make analyzing embedded library version easier for you, we now resort to exact dependency versions: javascript-modules-engine/package.json

All of our npm packages are now published with a provenance certificate, certifying that packages were built and published from a trusted environment.

We are making efforts to minimize the possibility

1.0.1Télécharger

This release only contains bug fixes.

Bug Fixes

The name in package.json can now be overriden by jahia.name to allow a wider range of characters. (#525)
Enabled support for yarn create @jahia/module. (#527)
Bumped React from 19.2.1 to 19.2.2. (#523)
Expose react-dom as a shared library. (#522)
Type JCR-SQL2 query results as JCRNodeWrapper. (#538)
Allow both react-i18next 15 and 16. (#541)

Full Changelog: 1_0_0...1_0_1

1.0.0Télécharger

JavaScript Modules are now considered stable! This also means that no breaking changes are coming in the foreseeable future.

Breaking Changes

Deprecated RenderInBrowser and HydrateInBrowser were removed. (#497)

Please read the 0.9 release notes for migration details.

Bug Fixes

Running JSM engine on bare metal Windows is now expected to work properly. (#504, #511)

Other Changes

The npm create @jahia/module@latest command creates a slightly smaller Hello World. (#501)
The JSM engine now ships with React 19.2.0. (#513)

Full Changelog: 0_9_2...1_0_0

0.9.2Télécharger

Bug Fixes

Ensure all builds (client and server) succeed before running the yarn watch:callback command (#492)
Add a health check to postgres in the docker-compose.yml of the create module (#494)

Full Changelog: 0_9_1...0_9_2

0.9.1Télécharger

Bug Fixes

Ensure hydration paths are resolved correctly on Windows (#484)

Full Changelog: 0_9_0...0_9_1

0.9.0Télécharger

This is the last release before the v1!

Breaking Changes

<Island /> is the new client-side component, replacing <HydrateInBrowser /> and <RenderInBrowser />. (#447)

To migrate, replace <HydrateInBrowser child={Comp} ... /> with <Island component={Comp} ... /> and <RenderInBrowser child={Comp} ... /> with <Island clientOnly component={Comp} ... />.

The documentation for this new component is already available on the Academy!

This change aligns with Island Architecture, and hides the implementation details: the fact that islands are hydrated is true in React 19, but might change in the future if React changes paradigm.

Note: HydrateInBrowser are RenderInBrowser deprecated, and will be removed in the next major version. This 0.9 version acts as a migration window before the v1.
Server-side dist bundle now uses standard ESM imports instead of a custom library sharing mechanism. (#463)

This does not change anything for your code but requires re-building your JavaScript Modules with the latest version of the Vite plugin.

Removed deprecated APIs:

Removed defineJahiaComponent and registerJahiaComponents, use jahiaComponent instead. (#421)
Removed areaView, allowedTypes and areaType from <(Absolute)Area /> components. Use view, allowedNodeTypes and nodeType instead. (#421)
Updated <AddContentButtons /> to only accept nodeTypes as an array of strings. (#421)

Bug Fixes

GraphQL query results are now properly encoded. (#422)

Dependency Bumps

The following embedded dependencies were bumped:

Dependency	Version
react	19.1.1
i18next	25.4.2
react-i18next	15.7.3

Full Changelog: 0_8_0...0_9_0

0.8.0Télécharger

This release adds support for Vite-powered asset bundling.

Breaking Changes

The Vite plugin no longer inlines all resources! This is an important change for both performance and security. (#275)

What it means in practice is that instead of two output folders (client and server), there are now three output folders:
- server: contains a single JS file to run on the server
- client: contains all JS files used for hydration
- assets: contains a single CSS file (style.css), with resources referenced in CSS and JS files (fonts, images...)
Assets will be deduplicated between client and server builds.

The configuration structure of the plugin changed to reflect this new folder. Here is the new default configuration:
```
jahia({
  inputDir: "src",
  outputDir: "dist",
  assetsDir: "assets", // Computed as dist/assets
  client: {
    inputGlob: "**/*.client.{jsx,tsx}", // Computed as src/**/*.client.{jsx,tsx}
    outputDir: "client", // Computed as dist/client
  },
  server: {
    inputGlob: "**/*.server.{jsx.tsx}", // Computed as src/**/*.server.{jsx,tsx}
    outputFile: "server/index.js", // Computed as dist/server/index.js
  },
})
```

If you follow our conventions regarding file names (see the globs above), you can safely remove all pre-0.8 configuration settings.

You will need to update your CSS import: <AddResources type="css" resources={buildModuleFileUrl("dist/assets/style.css")} /> (assets instead of server)

You may now restrict web-accessible resources in your package.json: "static-resources": "/dist/client,/dist/assets"
The jahia-deploy CLI has been rewritten to improve the development experience: CND breaking change validation is now skipped during development, allowing easier prototyping. The new CLI always uses the provisioning API. (#378)
Hydration markers now use custom elements instead of <div>s to prevent invalid HTML. All custom elements are prefixed by jsm- to avoid collisions. The new elements used are jsm-hydrate, jsm-render and jsm-children. (#386)

New Features

The npm create @jahia/module@latest CLI has been revamped to offer different templates to start your integration with. (#407)

You can now choose between 3 different bases:
- A minimal Hello World template set (this was the only available base previously)
- An empty template set
- An empty module
Newly created modules now ship with a docker-compose.yml file to ease the creation process of a local Jahia instance. (#364)
RenderChild and RenderChildren now accept a nodeTypes prop, used in page builder to restrict the node types that can be added as children. (#379)
Vite 7 is now officially supported! (#387)
buildModuleFileUrl keeps base64 URLs untouched instead of crashing. This features pairs well with Vite's assets handling. (#394)

Embedded JS Packages

No breaking changes here, we bumped JSM dependencies to the following versions:

react: 19.1.0
i18next: 25.3.2
react-i18next: 15.6.0

Full Changelog: 0_7_2...0_8_0

0.7.2Télécharger

No changes from 0.7.1

0.7.1Télécharger

This is a small developer experience release:

New JavaScript Modules are created with a docker-compose.yml file to start Jahia more easily. (#320)

Use npm init @jahia/module to create a new module with the improved local setup, or copy the file from GitHub.
Performance: insert <link rel="modulepreload"> to improve client-side JS load performance. (#349)

Full Changelog: 0_7_0...0_7_1

0.7.0Télécharger

This release adds support for JS<->Java interactions through OSGi services.

New Features

JS code can interact with Java code through OSGi services. Usage looks roughly like this:

import { jahiaComponent, server } from "@jahia/javascript-modules-library";

jahiaComponent(
  {
    nodeType: "javascriptExample:testOSGi",
    name: "default",
    componentType: "view",
  },
  () => <p>{server.osgi.getService("org.example.services.SimpleService").sayHello("World")}</p>,
);

The documentation will be updated shortly with more details on how to use this feature. In the meantime, you can check #294 for more examples. If you have feedback on this feature, please reach out to us: calendar.app.google/LigWTiUSDeHmVCwa7
JS client files are now minified. This should save up to 1 MB of client-side JavaScript for cold page loads! #269
process.env.NODE_ENV is now replaced during the build. This change makes JavaScript Modules more compatible with the rest of the Node.js ecosystem. #263
Sourcemaps are generated by default in development mode. #272

Breaking Changes

buildNavMenu has been removed. #282

Dependency Updates (#299)

All runtime dependencies have been updated to the latest versions. This includes:

i18next: 23.10.1 → 25.0.2 (🚨 Check i18next.com/misc/migration-guide for breaking changes affecting you)
react: 19.0.0 → 19.1.0
react-i18next: 15.4.0 → 15.5.1
styled-jsx: 5.1.6 → 5.1.7

Other Changes

All packages of this monorepo are now published to maven/npmjs.com on every commit. You can check the versions tab to install pre-release versions. Be careful, pre-releases do not go through our QA step. #254 and #281
You should no longer experience issues with jExperience and page-level personalization. #295
GraalVM is now correctly detected. #293

Full Changelog: 0_6_1...0_7_0

0.6.1Télécharger

JavaScript Modules are not compatible with Jahia 8.2.0.x.

This releases enforces that by raising the minimum Jahia version to 8.2.1.0.

This release contains a lot of breaking changes since the last published version of JavaScript Modules Engine:

(Note: 0.4 does not have exposed breaking changes)

0.5.3brouillonTélécharger

feat: Integrate @jahia/create-module into the monorepo to follow the same versioning. The template now uses Vite (instead of Webpack).
fix(vite-plugin): skip client build if it has no entry files

All changes: https://github.com/Jahia/javascript-modules/compare/0_5_1...0_5_3

0.5.1brouillonTélécharger

Welcome Vite! ⚡️

This release is a fairly large release with a major architectural rewrite on our end. This means a lot of breaking changes on your end too (sorry about that) but that's for the best: we replaced Webpack with Vite.

We heard your feedback about Webpack and decided to solve it by removing it altogether. If you're not familiar with Vite (and Webpack btw), it's a bundler: it takes source code in various languages (JS, TS, CSS, SCSS...) and produces a coherent output that the runtime can understand (e.g. JS+CSS for the browser).

All your configuration needs should be handled by a newcomer in this repository: @jahia/vite-plugin. It's a Vite plugin that takes care of everything for you:

import { defineConfig } from 'vite'
import jahia from '@jahia/vite-plugin'

export default defineConfig({
  plugins: [
    // ✨ And voilà!
    jahia()
  ]
})

There's no migration guide to migrate from Webpack to Vite—there's too much to cover—so instead we offer you a migration session with our Developer Advocate, @GauBen: → Book an appointment

Changelog

Build your JavaScript Modules with Vite and enjoy all its features out of the box: TypeScript transpilation, CSS Modules, raw imports, CSS preprocessors...
@jahia/javascript-modules-library is now written in TypeScript, with slightly stricter types, helping you find bugs before even running your code. As far as you're concerned, it's only a typing library, its runtime is handled by the JavaScript Modules Engine.
React 19! We bumped the supported React version and enabled support for the modern JSX transform.
The client directory (src/client) no longer needs to be flat, you can nest and organize your components the way you like.
Hydration now supports a larger range of objects: your props can be Map, Set, Date objects and more.
<AddContentButtons /> now takes a list of node types: <AddContentButtons nodeTypes={['ns:text', 'ns:richText']} />

Registering your components is now simpler, we added a jahiaComponent function that takes care of both the declaration (formerly defineJahiaComponent) and the registration (formerly registerJahiaComponents):

jahiaComponent(
  {
    nodeType: "ns:foobar",
    displayName: "My fancy content type",
    componentType: "view",
  },
  ({ foo, bar }, { currentNode }) => {
    // ^^^ props  ^^^ server context
    return (
      <p>
        {foo} {bar}
        <a href={currentNode.getUrl()}>Read more</a>
      </p>
    );
  },
);

Our Vite plugin supports glob entrypoints, allowing you to get rid of all the export * from ... statements
Under the hood, as we completely removed Webpack for both frontend and backend code, we no longer use Webpack Module Federation. Instead, we leverage a standard JS feature: <script type="importmap">. If you want to support old web browsers (see unsupported browsers), you'll have to add es-module-shims to your Jahia instance.

All changes: 0_4_0...0_5_1

0.3.0Télécharger

Rename from "NPM Modules" => "JavaScript Modules"
Introduce dependency to javascript-modules-engine in all JS modules
New helpers to build URLs
Easier way to generate URLs for resources in static folder
Simplification of folder structure
Production build config for npm-module-engines and JS modules
Update version or Yarn (no pnp)
Remove dependencies of libraries that are provided by Jahia at runtime: react, i18next, react-i18next, prop-types
Merge npm-modules-engine and js-server-core in one open source Github repo: https://github.com/Jahia/javascript-modules