Concerto 5.0.0 converts the internal modules of @accordproject/concerto-core,
@accordproject/concerto-util, @accordproject/concerto-cto and
@accordproject/concerto-vocabulary from TypeScript's CommonJS-interop export syntax
(export = X) to native ES module syntax (export default X / export { X }). This
was done under issue #1304
(see PR #1306) so that bundlers
can tree-shake unused exports out of applications that only need part of the API.
Who is affected: almost nobody. If your code imports Concerto packages by their
package name — require('@accordproject/concerto-util') or
import { Writer } from '@accordproject/concerto-core' — nothing changes and you can
upgrade without edits. You are only affected if your code reaches past the package
root into a package's built internals, e.g.
require('@accordproject/concerto-util/dist/writer').
This change applies to all packages in this monorepo: @accordproject/concerto-core,
@accordproject/concerto-util, @accordproject/concerto-cto,
@accordproject/concertino, @accordproject/concerto-vocabulary,
@accordproject/concerto-analysis, and @accordproject/concerto-linter. All of them
move to 5.0.0 together to keep their versions in lockstep.
Run these against your own codebase. Anything they print is worth checking against the "Breaking changes" section below.
# CommonJS deep requires into a package's compiled internals
grep -rn "require(['\"]@accordproject/concerto-[a-z-]*/dist/" .
# ESM deep imports into a package's compiled internals
grep -rn "from ['\"]@accordproject/concerto-[a-z-]*/dist/" .If those commands find nothing, you are not affected — upgrade and move on. If they find something, look at what is being imported:
- Importing a class deep path (e.g.
.../dist/writer,.../dist/filewriter,.../dist/modelmanager) and constructing it directly (new Writer()) is the pattern that breaks. See "Breaking changes" below. - Importing an object/namespace module (e.g.
.../dist/label,.../dist/identifiers,.../dist/warning,.../dist/modelwriter,.../dist/errorcodes) and reading named functions or constants off it is unaffected — those modules were already plain named exports.
Note that ModelUtil (concerto-core/dist/modelutil) looks like a namespace but is
a class of static methods, so it is in the first category, not the second.
Bundlers can only tree-shake (drop unused code from a bundle) when a module's exports
are statically analyzable ES module export statements. Concerto's TypeScript source
previously used export = X, a CommonJS-interop construct that compiles to
module.exports = X and cannot be statically analyzed by an ESM-aware bundler. That
prevented import-level tree-shaking of concerto-core and concerto-util, even though
the packages already published an ESM build.
5.0.0 changes the source to native ESM: import X from './x' / import * as NS from './ns' on the way in, and export { X }; export default X; on the way out, for each
class-shaped module. This is a purely mechanical, low-level TypeScript compilation
detail, but it has a real runtime effect on require():
export = Xcompiles tomodule.exports = X, sorequire('./x')returns the bare class —new (require('./x'))()works.export default X(compiled undermodule: commonjs) compiles toexports.default = X(alongsideexports.X = X), sorequire('./x')returns an object,{ default: X, X }—new (require('./x'))()now throws, because the thing you got back is a plain object, not the class.
No tsconfig flag changes this: it is how the TypeScript compiler has always lowered
these two export forms to CommonJS. There was no way to keep both export = (for old
deep require() callers) and export default (for tree-shaking) on the same module at
once, so this is a deliberate, scoped breaking change confined to deep imports.
Before (4.x):
const Writer = require('@accordproject/concerto-util/dist/writer');
const writer = new Writer();After (5.0.0) — this throws TypeError: Writer is not a constructor. Fix it by
destructuring the named export, or reading .default:
const { Writer } = require('@accordproject/concerto-util/dist/writer');
const writer = new Writer();
// or
const Writer = require('@accordproject/concerto-util/dist/writer').default;
const writer = new Writer();Preferred: stop importing the built file at all and import from the package root instead (see "Recommended migration path" below).
Before (4.x) — a default import worked because export = interop makes the whole
module the default:
import Writer from '@accordproject/concerto-util/dist/writer';
const writer = new Writer();After (5.0.0) — this breaks too. The ./dist/* subpath resolves to the
CommonJS build, and when an ESM importer loads a CommonJS module the default import
is bound to module.exports — which is now the { default: Writer, Writer } object
rather than the class. Use a named import instead; it works in both module systems:
import { Writer } from '@accordproject/concerto-util/dist/writer';
const writer = new Writer();Before (4.x): three packages published a webpack-built UMD bundle for direct browser
consumption via a <script> tag. The bundle exposed a global named after the package —
which is not a valid JavaScript identifier, so it was read off window:
<script src="https://cdn.jsdelivr.net/npm/@accordproject/concerto-core/dist/concerto-core.js"></script>
<script>
const { Factory, ModelManager } = window['concerto-core'];
</script>The same packages also set the legacy top-level browser field in package.json to
point at these bundles, for bundlers that predate the exports field.
The bundles were at:
@accordproject/concerto-core:dist/concerto-core.js@accordproject/concerto-util:dist/concerto-util.js@accordproject/concerto-cto:dist/concerto-cto.js
After (5.0.0) — the UMD bundles and the browser field are removed. They are gone
in all three packages with no drop-in replacement.
What actually changed:
- For bundler users (webpack 5+, Vite, Rollup, esbuild): nothing. These read the
exportsmap, which takes precedence over the legacybrowserfield, so they were already resolving to the browser ESM graph atdist/esm-browser/index.mjsrather than the UMD bundle. Removing the bundle takes away something they had stopped using. Your code needs no edits. - For
<script>tag users with no build step: you were relying on the UMD bundle's global namespace. That is gone. Your options are:- Add a bundler to your build (webpack, esbuild, Rollup, Vite). Bundle the package with your own code and import normally.
- Load the ESM graph as a module, with
<script type="module">and animportstatement. Note thatdist/esm-browser/index.mjsis a module graph, not a single file — it imports sibling chunks by relative path, andconcerto-core's graph additionally imports@accordproject/concerto-ctoand@accordproject/concerto-utilas bare specifiers. Serving it therefore needs either a CDN that rewrites those specifiers into resolvable URLs, or an import map that maps them yourself. Check the behaviour of whichever CDN you use before relying on it.
- For tooling that does not read
exportsat all (webpack 4, browserify, Parcel 1): this is the sharp edge. Those tools previously found the UMD bundle through the top-levelbrowserfield. With both removed they fall back tomain, which is the CommonJS build — it importsfsand other Node builtins, so it will not run in a browser, and the failure surfaces as a confusing missing-module error rather than a clear one. There is no supported path for these tools in 5.0.0; upgrade to a bundler that understandsexports.
The browser condition in exports (which points to dist/esm-browser/index.mjs) is
still there and still in use — bundlers automatically pick it when targeting the web. But
the old UMD distribution is gone, and there is no window['concerto-core'] global
anymore.
Every single-class module in the four migrated packages moved from export = to
export default / export { X }:
concerto-util—Writer,FileWriter,InMemoryWriter,TypedStack,Logger,BaseException,BaseFileException,FileDownloader, and the file loaders.concerto-core—ModelManager,Factory,Serializer,ModelFile,Introspector,ModelUtil, and the various*Declaration/*Validatorclasses.concerto-cto—ParseException. TheParser,PrinterandExternalmodules were object exports and stay object-shaped, but they now also expose their members as individual named exports (parse,parseModels,toCTO,resolveExternal,createDefaultFileDownloader), which is what makes them tree-shakeable.concerto-vocabulary—Vocabulary,VocabularyManager.
Any of these you deep-import and construct directly needs the fix above (or, better, a root import).
If you were reaching into a package's types/ declaration tree — e.g.
import type { ClassDeclaration } from '@accordproject/concerto-core/types/lib/introspect/classdeclaration'
— stop. That path is not part of the package's export surface and is not guaranteed to
resolve under node16/nodenext or bundler module resolution. Import the type from
the package root instead:
import type { ClassDeclaration, ModelFile } from '@accordproject/concerto-core';import type is erased at compile time, so it costs nothing at runtime and cannot
anchor a module into your bundle — which is exactly why it is the right tool here, and
why the packages deliberately do not widen their exports map to re-expose the
types/ tree. If a type you need is not reachable from the root, please open an issue
asking for it to be exported rather than deep-importing the declaration file.
In 4.x a package had no exports map and no module field, so import and require
both resolved to the same CommonJS file: one copy of every class, in one process. From
5.0.0 they resolve to different files, and Node loads each independently. A process
that reaches a package both ways therefore holds two copies of it, with two sets of
class identities:
import { ModelManager, Factory } from '@accordproject/concerto-core';
const concerto = createRequire(import.meta.url)('@accordproject/concerto-core');
ModelManager === concerto.ModelManager; // 4.x: true — 5.0.0: falseMost of the API is duck-typed and survives this, but the instanceof guards do not.
The failure is not subtle when it happens:
const resource = new Factory(modelManager).newResource('org.example@1.0.0', 'Order', 'o1');
new concerto.Serializer(...).toJSON(resource);
// Error: "Serializer.toJSON" only accepts "Concept", "Event", "Asset",
// "Participant" or "Transaction".This is the standard dual-package hazard, and it is inherent to shipping both module systems. It only bites a process that loads a package twice, so:
- Pick one module system per process for a given package. In an ESM application,
importthe package; don't alsocreateRequireit. - Watch for a CommonJS dependency in an ESM app. A library that still uses
require('@accordproject/concerto-core')internally has its own copy. Objects can cross that boundary safely, butResources andClassDeclarations created on one side must be handed back to that same side to be serialized or validated. Where a library re-exports concerto types for you (@accordproject/template-enginere-exportsModelManagerfor exactly this reason), import them from the library rather than from@accordproject/concerto-coredirectly. - Check for a duplicate before debugging anything stranger. If an
instanceofor aSerializerguard fails on an object that is obviously the right type, runnpm ls @accordproject/concerto-coreand confirm you aren't loading it twice.
The ESM migration replaced require() with import, which restored real types across
package boundaries where require() had been producing any. Three signatures turned
out not to describe what the code actually does, and were being held together by casts.
They are corrected here rather than papered over, because a major release is the only
place that can happen. All three are type-level changes: runtime behaviour is
unchanged, apart from one error message noted below.
Comparer.compareClassDeclaration receives a Declaration, not a ClassDeclaration
(@accordproject/concerto-analysis). Every declaration in a model file is put through
this callback, including MapDeclaration and ScalarDeclaration — neither of which is a
ClassDeclaration. That has always been true at runtime; only the type said otherwise.
If you write custom comparers in TypeScript and reach for something only a
ClassDeclaration has, you now get a compile error where you previously got a runtime
crash on a model containing a map or scalar:
const myComparer: ComparerFactory = () => ({
compareClassDeclaration: (a, b) => {
a?.getOwnProperties(); // 5.0.0: compile error — narrow first
if (a instanceof ClassDeclaration) {
a.getOwnProperties(); // fine
}
a?.getName(); // fine — Declaration-level, unchanged
}
});FileDownloader takes a second type parameter (@accordproject/concerto-util):
FileDownloader<TFile, TSeed = TFile>. The files you seed the walk with are not
necessarily the type the bound FileLoader produces — ModelManager seeds it with
parsed ModelFiles and gets back raw sources — and one type parameter could not say
that. TSeed defaults to TFile, so existing single-parameter uses are unaffected.
ModelManager.writeModelsToFileSystem reports unwritable models properly. A
ModelFile built from an AST alone has no file name and no CTO source, so it cannot be
written to disk. This previously surfaced as a TypeError from inside fs; it now
throws an error naming the namespace that could not be written. Model managers loaded
from CTO — the overwhelmingly common case — are unaffected.
Root-package imports are unaffected — this is true for both CommonJS and ESM, and for every package in this release:
// CommonJS — unchanged
const { Writer, FileWriter, Logger, TypedStack } = require('@accordproject/concerto-util');
const { ModelManager, Factory, Serializer } = require('@accordproject/concerto-core');
// ESM — unchanged
import { Writer, FileWriter, Logger, TypedStack } from '@accordproject/concerto-util';
import { ModelManager, Factory, Serializer } from '@accordproject/concerto-core';Namespace/object modules that were already plain object exports are unaffected even
when deep-imported, because they never went through the export = vs export default
change described above. In concerto-util these are label, identifiers,
errorcodes, warning, and modelwriter (re-exported from the package root under the
names Label, Identifiers, ErrorCodes, Warning and ModelWriter):
// the module's own named exports — unchanged
const { writeModelsToFileSystem } = require('@accordproject/concerto-util/dist/modelwriter');
writeModelsToFileSystem(files, path, options);
// or, preferred, via the root barrel's namespace re-export
const { ModelWriter } = require('@accordproject/concerto-util');
ModelWriter.writeModelsToFileSystem(files, path, options);-
Prefer root-package named imports. This is the supported, stable contract and is unaffected by this release regardless of module bundler or module system:
import { Writer, ModelManager, Factory } from '@accordproject/concerto-core';
concerto-core's root barrel re-exports (among others)ModelManager,Factory,Serializer,Introspector,ModelFile,ModelUtil,ModelLoader,DecoratorManager,Decorator,ClassDeclaration,Property,Field,Relationship,Resource, and the exception typesSecurityException/IllegalModelException/TypeNotFoundException/MetamodelException.concerto-util's root barrel re-exportsWriter,FileWriter,InMemoryWriter,Logger,TypedStack,BaseException,BaseFileException,FileDownloader, the file loaders (CompositeFileLoader,DefaultFileLoader,GitHubFileLoader,HTTPFileLoader), and the namespace modulesLabel,Identifiers,ErrorCodes,Warning,ModelWriter. Check a package'ssrc/index.ts(or its publisheddist/index.d.ts) for the authoritative, current list. -
Use
import typefor anything you only need in a type position. It is erased at compile time, keeps your bundle free of a runtime edge to the module, and is resolution-stable acrossnode16/nodenext/bundler:import type { ModelFile, Property } from '@accordproject/concerto-core';
-
If a symbol genuinely is not re-exported from the root, keep the deep import but update it to the new shape: a named destructure (
const { X } = require(...)) for CommonJS, or.defaultif you need the default export specifically. Consider opening an issue to ask for the symbol to be added to the root barrel instead of depending on the internal path long-term.
To benefit from the tree-shaking this release enables:
- Import via
import { Writer } from '@accordproject/concerto-util'(named ESM imports), notconst concertoUtil = require(...)/import * as concertoUtil from ...followed by property access — a bundler can only drop what it can see you don't use. - Build with a bundler that reads
package.json'sexports/modulefield and honorssideEffects(webpack, Rollup, esbuild, Vite all do this by default in production mode). @accordproject/concerto-utildeclares"sideEffects": false, so a compliant bundler can drop any export you don't import.@accordproject/concerto-coredeclares"sideEffects": ["./dist/dayjs-setup.js", "./dist/esm/dayjs-setup.mjs", "./dist/esm-browser/dayjs-setup.mjs"]— everything else is safe to drop, but those modules run global setup code (dayjsplugin registration) as a side effect and are always kept.
The ESM build ships one output module per source module (with shared code hoisted into chunks), mirroring the CJS build, so your bundler can drop whole modules you never reach.
Measured with esbuild --bundle --minify --format=esm, importing each package by
name so that resolution happens the way it would in your project (4.2.0 has no
exports map, so a browser bundler takes its browser field — the UMD bundle — while
5.0.0 resolves the browser condition to dist/esm-browser):
| What you import | 4.2.0 | 5.0.0 | |
|---|---|---|---|
{ Writer } from concerto-util |
95,570 B | 1,050 B | −98.9% |
{ SecurityException } from concerto-core |
903,570 B | 4,064 B | −99.6% |
{ ModelManager } from concerto-core |
903,565 B | 419,416 B | −53.6% |
Bundling for Node instead (--platform=node, which takes 4.2.0's main and 5.0.0's
import condition):
| What you import | 4.2.0 | 5.0.0 | |
|---|---|---|---|
{ Writer } from concerto-util |
28,647 B | 863 B | −97.0% |
{ SecurityException } from concerto-core |
559,234 B | 3,831 B | −99.3% |
{ ModelManager } from concerto-core |
559,229 B | 426,781 B | −23.7% |
ModelManager genuinely reaches most of the package (introspection, serialization and
the CTO parser), so it shrinks least — that is the honest floor, not a bug. Importing
the whole package costs about what it always did.
Every package in this release ships a dual-package exports map (CJS + ESM + types),
plus the legacy main/module/typings fields for tooling that doesn't read
exports.
| Package | main (CJS) |
module (ESM) |
types |
|---|---|---|---|
concerto-core |
dist/index.js |
dist/esm/index.mjs |
dist/index.d.ts |
concerto-util |
dist/index.js |
dist/esm/index.mjs |
dist/index.d.ts |
concerto-cto |
dist/index.js |
dist/esm/index.mjs |
dist/index.d.ts |
concertino |
dist/index.js |
dist/esm/index.mjs |
dist/index.d.ts |
concerto-vocabulary |
dist/index.js |
dist/esm/index.mjs |
dist/index.d.ts |
concerto-analysis |
dist/index.js |
dist/esm/index.mjs |
dist/index.d.ts |
concerto-linter |
dist/index.js |
dist/esm/index.mjs |
dist/index.d.ts |
Every package's exports map has the same shape (shown here for concerto-core;
concerto-util is identical apart from the package name):
"exports": {
".": {
"types": "./dist/index.d.ts",
"browser": "./dist/esm-browser/index.mjs",
"import": "./dist/esm/index.mjs",
"require": "./dist/index.js"
},
"./package.json": "./package.json",
"./dist/*": "./dist/*"
}Two ESM graphs are published, built from the same entry points and exposing the same named exports. They differ only in how Node builtins are handled:
| Graph | Selected by | Node builtins |
|---|---|---|
dist/esm |
the import condition — Node, and node-target bundlers |
real fs/path, imported normally |
dist/esm-browser |
the browser condition — webpack, Vite, Rollup and friends targeting the web |
stubbed to empty modules |
The split matters for the handful of APIs that touch the file system —
FileWriter, ModelWriter.writeModelsToFileSystem and ModelLoader. In the browser
graph those are inert by construction (the fs and path modules are stubbed); under
Node they behave exactly as they do in CommonJS. Nothing in your code selects between
the graphs — your runtime or bundler does.
The "./dist/*" subpath is what still permits deep imports at all (it is not removed
in this release) — it is the compiled shape of those modules, described above, that
changed. The types/ declaration tree is deliberately not mapped in exports: use
import type from the package root instead (see "Type-only imports" above).
If you hit an import that this guide doesn't cover, please open an issue at https://github.com/accordproject/concerto/issues and reference #1304, the tracking issue for this migration.
Accord Project source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the LICENSE file. Accord Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0), available at http://creativecommons.org/licenses/by/4.0/.