Skip to main content

Transpile

Transpiling converts a modularized ADITO project into a flat, standalone project for deployment. During this process, all dependencies, Modifications, ExtensionPoints, and Services are resolved into a unified codebase. The transpiled output is written to the project's dist directory.

Transpile modes​

  • Full transpile: Processes the entire project and generates a complete output.

  • Partial transpile: Processes only files changed since the last transpile. If an incremental step is not possible or the last transpile failed, a full transpile is executed automatically.

info

Partial transpile reduces turnaround time during development. The system automatically falls back to a full transpile when required to maintain consistency.

Running a transpile​

You can start a transpile in the Designer via the toolbar "hammer" button (partial transpile) or the project context menu (partial and full transpile).

hammer
Figure: Toolbar action (hammer) for triggering a transpile

partial full transpile
Figure: Context menu options for partial and full transpile

  • A transpile is automatically triggered when deploying a modularized project to the database.
  • Several Designer actions can optionally trigger a transpile via a checkbox in their dialogs.

How transpiling works​

The transpiler executes several internal phases. While the set of phases may evolve, the core tasks are:

  • Determine all modules referenced as dependencies.
  • Copy their relevant files into the dist directory.
  • Collect and apply Modifications from all modules.
  • Resolve Extension Points and Services.

Although transpiling is usually executed on packages of type "project," it can also run on packages of type "module" without deployment. This is useful to:

  • Inspect the transpiled result for a specific Modification or Service.
  • Exchange content manually during local development.
note

Running the transpiler on a single module does not deploy anything. It only produces a resolved output for inspection or local usage.

.transpilerignore​

Use a .transpilerignore file to exclude files or folders from the transpile process. The file must reside at the project root (next to package.json).

During transpiling, the transpiler uses the .transpilerignore files of the currently processed module and the executing package to determine exclusions.

tip

The .transpilerignore file uses the same syntax as the .gitignore file.

Add clear, descriptive comments (lines starting with #) in your .transpilerignore to explain why each pattern is ignored.

Example file:

# Git
.git
.gitignore
.gitattributes
.gitlab-ci.yml
README.md
CHANGELOG.md

# ADITO
.aditoprj
data
dist
others
scripts
jsconfig.json
jsconfig.template.json
.eslintrc.json
eslint.config.mjs

# NPM
node_modules
package.json
package-lock.json
.npmrc

# IntelliJ
.idea

# VS Code
.vscode

# Transpiler
cache.txt
cacheMods.txt

If your .transpilerignore file contains the entry foo/bar, the transpiler will process the foo folder as usual but ignore everything inside foo/bar (for example, foo/bar/baz.txt and foo/bar/lorem/ipsum.txt).

tip

Exclude generated folders (e.g., dist) and large directories (e.g., node_modules) to speed up transpiling and avoid unnecessary file processing.

Conflict handling: multiple dependencies (diamond problem)​

A diamond conflict occurs when two or more dependent modules override the same property originating from a shared base module. Because the precedence is ambiguous, the transpiler cannot decide which Modification should apply and aborts with an error.

Example scenario:

If Module Beta and Module Gamma both modify MyContextAlpha.mainView from Module Alpha, and Module Delta depends on Alpha, Beta, and Gamma, the transpiler cannot determine whether mainView should come from Beta or Gamma, because both modules modify it.

The transpiler detects such diamond conflicts and fails with an error:

Example log message for diamond problem
[INFO ] --------------- < Resolving Modifications > ----------------
[INFO ] 
[INFO ] @aditosoftware/module-beta:1.0.0 and @aditosoftware/module-gamma:1.0.0 are overriding the property MyContextAlpha/mainView with a different value: 
[INFO ]  - @aditosoftware/module-beta:1.0.0: ModuleBetaMain_view
[INFO ]  - @aditosoftware/module-gamma:1.0.0: ModuleGammaMain_view
[INFO ]  -> Resolving Diamond with @aditosoftware/module-delta:1.0.0
[INFO ] 
[ERROR] ------------------------------------------------------------
[ERROR] BUILD FAILED
[ERROR] ------------------------------------------------------------
[ERROR] Total time: 0:00 min
[ERROR] Finished at: 2025-10-20T07:24:06.776905Z
[ERROR] ------------------------------------------------------------
[ERROR] 
[ERROR] @aditosoftware/module-beta contains changes targetting the same property as @aditosoftware/module-gamma does, so this conflict has to be resolved within the common ancestor @aditosoftware/module-delta. The resolving change could not be found.
[ERROR] 
[ERROR] See the IDE-Log file for more information.
[ERROR] If you need more in-depth information of the transpilation process, set -Dadito.modularization.logging.debug
[ERROR] 
[ERROR] ------------------------------------------------------------

This message indicates the transpiler found a diamond conflict and attempted to resolve it with any value from module-delta, but no explicit resolving Modification exists.

To resolve this conflict, you need to define an explicit Modification of MyContextAlpha.mainView in Module Delta:

  • Reuse an existing value: mainView = ModuleBetaMain_view or mainView = ModuleGammaMain_view
  • Provide a new value: mainView = ModuleDeltaMain_view

You can set this directly in the Designer via the Property Editor by explicitly selecting the value to use. The Designer will create the corresponding Modification automatically.

Logging​

Progress and diagnostics are written in the "Output - Build" window.

  • ERROR: Indicates failures. May also appear in successful builds for severe issues that require attention.
  • WARN: Highlights potential problems that can lead to silent errors or future failures. These should be addressed.
  • INFO: General information about the current transpile phase and actions.
  • DEBUG: Detailed diagnostic output. Enable via JVM parameter -J-Dadito.modularization.logging.debug in ADITODesigner.conf.
tip

You should always check your log output for ERROR and WARN messages.

Treat ERROR and WARN messages as actionable. Resolve them promptly to avoid deployment issues or hidden inconsistencies.

If you are unsure about the meaning of a log message, contact the Transpiler development team. They will help you interpret the message and suggest next steps.

Below are common warnings and their resolutions.

Duplicate elements​

Example log message for duplicate elements
[WARN ] Found duplicate elements in location 'entity\EmailGenerator_entity' from multiple modules:
[WARN ]  - @aditosoftware/ai-email-generator:1.0.0 has 1 element(s):
[WARN ]   - entity\EmailGenerator_entity\entityfields\airesponse\valueProcess.js
[WARN ]  - @aditosoftware/correspondence:5.0.1 has 11 element(s):
[WARN ]   - entity\EmailGenerator_entity\EmailGenerator_entity.aod
[WARN ]   - entity\EmailGenerator_entity\afterUiInit.js
[WARN ]   - entity\EmailGenerator_entity\entityfields\attacheddocuments\valueProcess.js
[WARN ]   - entity\EmailGenerator_entity\entityfields\content\valueProcess.js
[WARN ]   - entity\EmailGenerator_entity\entityfields\documenttemplates\children\comingfrom_param\valueProcess.js
[WARN ]   - and 6 more occurrences... 
[WARN ] Note that elements from different modules result in only the last one being applied and used.
[WARN ] The applied module might or might not change between different transpile runs.
[WARN ] Duplicate elements also result in unnecessary delete and write operations.
[WARN ] Either add those files to the .transpilerignore file or contact the module developer so that duplicate elements can be removed.

Meaning: The same element is contributed by multiple modules. Only one copy is kept, and the winner may vary between transpile runs.

Impact:

  • Non-deterministic results across transpiles
  • Older logic may override newer logic
  • Extra file churn during transpile/deploy

Resolution:

  • Temporary local workaround: remove the redundant copy from node_modules (will be restored by npm/yarn).
  • Permanent fix:
    • If the duplicate is non-essential (e.g., changelogs, README-like files), add it to .transpilerignore.
    • Otherwise, coordinate with the module owner(s) to keep a single authoritative element.

Not applying modification ...​

Multiple warnings start with "Not applying modification...". Typical cases and fixes:

... because it is invalid​

Example log message for invalid modification
[WARN ] Not applying modification My-Modification-a6-b3c3-df6724218f4e, because it is invalid

Cause: The Modification’s AOD structure is invalid.

Fix: Inspect the referenced Modification. Remove or correct unexpected tags/elements that should not be present.

... because target model type is invalid​

Example log message for target model type invalid modification
[WARN ] Not applying modification My-Modification-a6-b3c3-df6724218f4e, because target model type is invalid

Cause: <modelType> in the named modification contains an invalid value.

Fix: Open the AOD of the referenced Modification and set <modelType> to the correct type. You can infer the model type from the AODs top-level tag.

... because target model container does not exist​

Example log message for target model container does not exist modification
[WARN ] Not applying modification My-Modification-a6-b3c3-df6724218f4e, because target model container foo does not exist

Cause: The folder for the target model (specified in <modelName>) cannot be found.

Fix:

  • Search the whole project (including dependencies) for an element with the specified model name.
  • Validate the Modification’s content and whether it is still required.
  • Check for refactoring/renames that made the old name unresolved.
  • If renamed, update the Modification so modelName and path point to the new element.
  • If obsolete, remove the Modification to avoid repeated warnings.

... because target model does not exist​

Example log message for target model does not exist modification
[WARN ] Not applying modification My-Modification-a6-b3c3-df6724218f4e, because target model foo does not exist

Cause: The target model file is missing. Difference to the “container” case:

  • “Container does not exist”: folder (e.g., Car_entity) is missing.
  • “Model does not exist”: folder exists, but the model file inside (e.g., Car_entity.aod) is missing.

Fix:

  • Search the project and dependencies for the intended model.
  • Validate the Modification and whether it is still needed.
  • Check for refactoring/renames.
  • If renamed, update modelName and path.
  • Remove obsolete Modifications.

Failed to apply modification​

[WARN ] Failed to apply modification moduleTreeContent_service/implementations within moduleTreeContent_service to value task_impl

Meaning: The Modification could not be applied, or a referenced Extension Point or Service could not be resolved.

Fix:

  • Validate the Modification and its references.
  • Search the project and dependencies for the named data model/Modification/Extension Point/Service.
  • Verify the content is correct and still required.
  • Check for refactoring/renames and update modelName/path accordingly.
  • Remove obsolete Modifications to prevent recurring checks.

Transpile as Docker image​

You can execute the transpiler as a Docker image. This is useful in CI/CD pipelines to automatically verify that your project can be transpiled. You can also use this pipeline step to transpile and deploy your project automatically.

See the Docker Designer documentation for transpile usage in CI/CD.