@eventcatalog/core 5.1.0 → 5.2.0

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "5.1.0";
+var version = "5.2.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,8 +1,8 @@
 import {
   raiseEvent
-} from "../chunk-FHZXZWCY.js";
+} from "../chunk-66OL4B7U.js";
 import "../chunk-CPW6G62V.js";
-import "../chunk-OT57IOWN.js";
+import "../chunk-N2LLD5TR.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -169,7 +169,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "5.1.0";
+var version = "5.2.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,12 +1,12 @@
 import {
   log_build_default
-} from "../chunk-G3CHTDAE.js";
+} from "../chunk-RNYFUWJI.js";
 import "../chunk-AD7CL772.js";
-import "../chunk-FHZXZWCY.js";
+import "../chunk-66OL4B7U.js";
 import "../chunk-ZAZHAVKB.js";
 import "../chunk-CA6WCQ2T.js";
 import "../chunk-CPW6G62V.js";
-import "../chunk-OT57IOWN.js";
+import "../chunk-N2LLD5TR.js";
 import "../chunk-4G7FSRPN.js";
 export {
   log_build_default as default

package/dist/architecture-export.cjs

@@ -31,9 +31,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var architecture_export_exports = {};
 __export(architecture_export_exports, {
   getArchitectureExportPath: () => getArchitectureExportPath,
+  getCustomExportsDir: () => getCustomExportsDir,
+  hasCustomExports: () => hasCustomExports,
   isCatalogAuthEnabled: () => isCatalogAuthEnabled,
   resolveArchitectureExport: () => resolveArchitectureExport,
-  writeArchitectureExport: () => writeArchitectureExport
+  resolveCustomExports: () => resolveCustomExports,
+  writeArchitectureExport: () => writeArchitectureExport,
+  writeCustomExportsToBuild: () => writeCustomExportsToBuild
 });
 module.exports = __toCommonJS(architecture_export_exports);
 var import_node_fs = __toESM(require("fs"), 1);
@@ -60,10 +64,38 @@ var writeArchitectureExport = ({
   outputPath: getArchitectureExportPath({ outDir, isServer }),
   regenerateCommand: "npx eventcatalog build"
 });
+var resolveCustomExports = (config, { authEnabled }) => {
+  const enabled = config?.exports?.custom?.enabled;
+  if (enabled === false) return { enabled: false, reason: "disabled" };
+  if (authEnabled && enabled !== true) return { enabled: false, reason: "auth" };
+  return { enabled: true };
+};
+var hasCustomExports = ({
+  projectDir,
+  config
+}) => {
+  const folder = import_node_path.default.join(projectDir, config?.exports?.custom?.dir || import_exporters.DEFAULT_CUSTOM_EXPORTS_DIR);
+  return import_node_fs.default.existsSync(folder) && import_node_fs.default.readdirSync(folder).some((name) => /\.mdx?$/i.test(name));
+};
+var getCustomExportsDir = ({ outDir, isServer }) => import_node_path.default.join(outDir, isServer ? "client" : "", "exports");
+var writeCustomExportsToBuild = ({
+  projectDir,
+  outDir,
+  isServer,
+  config
+}) => (0, import_exporters.writeCustomExports)({
+  dir: projectDir,
+  outputDir: getCustomExportsDir({ outDir, isServer }),
+  config: config?.exports?.custom ?? {}
+});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getArchitectureExportPath,
+  getCustomExportsDir,
+  hasCustomExports,
   isCatalogAuthEnabled,
   resolveArchitectureExport,
-  writeArchitectureExport
+  resolveCustomExports,
+  writeArchitectureExport,
+  writeCustomExportsToBuild
 });

package/dist/architecture-export.d.cts

@@ -1,4 +1,5 @@
 import * as _eventcatalog_exporters from '@eventcatalog/exporters';
+import { CustomExportsConfig } from '@eventcatalog/exporters';
 
 /** The part of eventcatalog.config.js that controls the architecture reference. */
 interface ArchitectureExportConfig {
@@ -6,6 +7,7 @@ interface ArchitectureExportConfig {
         html?: {
             enabled?: boolean;
         };
+        custom?: CustomExportsConfig;
     };
 }
 /**
@@ -44,5 +46,27 @@ declare const writeArchitectureExport: ({ projectDir, outDir, isServer, }: {
     outDir: string;
     isServer: boolean;
 }) => Promise<_eventcatalog_exporters.WriteHtmlResult>;
+/** Custom exports (exports/*.mdx) follow the same rule as the reference: on unless turned off, and opt-in with auth. */
+declare const resolveCustomExports: (config: ArchitectureExportConfig | null | undefined, { authEnabled }: {
+    authEnabled: boolean;
+}) => ArchitectureExportDecision;
+/** Whether the catalog has any custom export files, so a catalog without them never hears about custom exports. */
+declare const hasCustomExports: ({ projectDir, config, }: {
+    projectDir: string;
+    config: ArchitectureExportConfig | null | undefined;
+}) => boolean;
+declare const getCustomExportsDir: ({ outDir, isServer }: {
+    outDir: string;
+    isServer: boolean;
+}) => string;
+declare const writeCustomExportsToBuild: ({ projectDir, outDir, isServer, config, }: {
+    projectDir: string;
+    outDir: string;
+    isServer: boolean;
+    config: ArchitectureExportConfig | null | undefined;
+}) => Promise<{
+    written: _eventcatalog_exporters.WrittenCustomExport[];
+    failed: _eventcatalog_exporters.CustomExportFailure[];
+}>;
 
-export { type ArchitectureExportConfig, type ArchitectureExportDecision, getArchitectureExportPath, isCatalogAuthEnabled, resolveArchitectureExport, writeArchitectureExport };
+export { type ArchitectureExportConfig, type ArchitectureExportDecision, getArchitectureExportPath, getCustomExportsDir, hasCustomExports, isCatalogAuthEnabled, resolveArchitectureExport, resolveCustomExports, writeArchitectureExport, writeCustomExportsToBuild };

package/dist/architecture-export.d.ts

@@ -1,4 +1,5 @@
 import * as _eventcatalog_exporters from '@eventcatalog/exporters';
+import { CustomExportsConfig } from '@eventcatalog/exporters';
 
 /** The part of eventcatalog.config.js that controls the architecture reference. */
 interface ArchitectureExportConfig {
@@ -6,6 +7,7 @@ interface ArchitectureExportConfig {
         html?: {
             enabled?: boolean;
         };
+        custom?: CustomExportsConfig;
     };
 }
 /**
@@ -44,5 +46,27 @@ declare const writeArchitectureExport: ({ projectDir, outDir, isServer, }: {
     outDir: string;
     isServer: boolean;
 }) => Promise<_eventcatalog_exporters.WriteHtmlResult>;
+/** Custom exports (exports/*.mdx) follow the same rule as the reference: on unless turned off, and opt-in with auth. */
+declare const resolveCustomExports: (config: ArchitectureExportConfig | null | undefined, { authEnabled }: {
+    authEnabled: boolean;
+}) => ArchitectureExportDecision;
+/** Whether the catalog has any custom export files, so a catalog without them never hears about custom exports. */
+declare const hasCustomExports: ({ projectDir, config, }: {
+    projectDir: string;
+    config: ArchitectureExportConfig | null | undefined;
+}) => boolean;
+declare const getCustomExportsDir: ({ outDir, isServer }: {
+    outDir: string;
+    isServer: boolean;
+}) => string;
+declare const writeCustomExportsToBuild: ({ projectDir, outDir, isServer, config, }: {
+    projectDir: string;
+    outDir: string;
+    isServer: boolean;
+    config: ArchitectureExportConfig | null | undefined;
+}) => Promise<{
+    written: _eventcatalog_exporters.WrittenCustomExport[];
+    failed: _eventcatalog_exporters.CustomExportFailure[];
+}>;
 
-export { type ArchitectureExportConfig, type ArchitectureExportDecision, getArchitectureExportPath, isCatalogAuthEnabled, resolveArchitectureExport, writeArchitectureExport };
+export { type ArchitectureExportConfig, type ArchitectureExportDecision, getArchitectureExportPath, getCustomExportsDir, hasCustomExports, isCatalogAuthEnabled, resolveArchitectureExport, resolveCustomExports, writeArchitectureExport, writeCustomExportsToBuild };

package/dist/architecture-export.js

@@ -1,12 +1,20 @@
 import {
   getArchitectureExportPath,
+  getCustomExportsDir,
+  hasCustomExports,
   isCatalogAuthEnabled,
   resolveArchitectureExport,
-  writeArchitectureExport
-} from "./chunk-E6WTCJUL.js";
+  resolveCustomExports,
+  writeArchitectureExport,
+  writeCustomExportsToBuild
+} from "./chunk-IR5MKGKS.js";
 export {
   getArchitectureExportPath,
+  getCustomExportsDir,
+  hasCustomExports,
   isCatalogAuthEnabled,
   resolveArchitectureExport,
-  writeArchitectureExport
+  resolveCustomExports,
+  writeArchitectureExport,
+  writeCustomExportsToBuild
 };

package/dist/{chunk-FHZXZWCY.js → chunk-66OL4B7U.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-CPW6G62V.js";
 import {
   VERSION
-} from "./chunk-OT57IOWN.js";
+} from "./chunk-N2LLD5TR.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/chunk-IR5MKGKS.js

@@ -0,0 +1,60 @@
+// src/architecture-export.ts
+import fs from "fs";
+import path from "path";
+import { DEFAULT_CUSTOM_EXPORTS_DIR, writeCustomExports, writeHtml } from "@eventcatalog/exporters";
+var isCatalogAuthEnabled = ({
+  config,
+  projectDir,
+  isServer
+}) => Boolean(config?.auth?.enabled) && isServer && fs.existsSync(path.join(projectDir, "eventcatalog.auth.js"));
+var resolveArchitectureExport = (config, { authEnabled }) => {
+  const enabled = config?.exports?.html?.enabled;
+  if (enabled === false) return { enabled: false, reason: "disabled" };
+  if (authEnabled && enabled !== true) return { enabled: false, reason: "auth" };
+  return { enabled: true };
+};
+var getArchitectureExportPath = ({ outDir, isServer }) => path.join(outDir, isServer ? "client" : "", "architecture.html");
+var writeArchitectureExport = ({
+  projectDir,
+  outDir,
+  isServer
+}) => writeHtml({
+  dir: projectDir,
+  outputPath: getArchitectureExportPath({ outDir, isServer }),
+  regenerateCommand: "npx eventcatalog build"
+});
+var resolveCustomExports = (config, { authEnabled }) => {
+  const enabled = config?.exports?.custom?.enabled;
+  if (enabled === false) return { enabled: false, reason: "disabled" };
+  if (authEnabled && enabled !== true) return { enabled: false, reason: "auth" };
+  return { enabled: true };
+};
+var hasCustomExports = ({
+  projectDir,
+  config
+}) => {
+  const folder = path.join(projectDir, config?.exports?.custom?.dir || DEFAULT_CUSTOM_EXPORTS_DIR);
+  return fs.existsSync(folder) && fs.readdirSync(folder).some((name) => /\.mdx?$/i.test(name));
+};
+var getCustomExportsDir = ({ outDir, isServer }) => path.join(outDir, isServer ? "client" : "", "exports");
+var writeCustomExportsToBuild = ({
+  projectDir,
+  outDir,
+  isServer,
+  config
+}) => writeCustomExports({
+  dir: projectDir,
+  outputDir: getCustomExportsDir({ outDir, isServer }),
+  config: config?.exports?.custom ?? {}
+});
+
+export {
+  isCatalogAuthEnabled,
+  resolveArchitectureExport,
+  getArchitectureExportPath,
+  writeArchitectureExport,
+  resolveCustomExports,
+  hasCustomExports,
+  getCustomExportsDir,
+  writeCustomExportsToBuild
+};

package/dist/{chunk-OT57IOWN.js → chunk-N2LLD5TR.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "5.1.0";
+var version = "5.2.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-TBXLUIJD.js → chunk-NBYKF4Z4.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-WBUSFEBH.js";
+} from "./chunk-XI5HQWM2.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-G3CHTDAE.js → chunk-RNYFUWJI.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-AD7CL772.js";
 import {
   raiseEvent
-} from "./chunk-FHZXZWCY.js";
+} from "./chunk-66OL4B7U.js";
 import {
   countResources,
   hashCatalogContent,

package/dist/{chunk-WBUSFEBH.js → chunk-XI5HQWM2.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-OT57IOWN.js";
+} from "./chunk-N2LLD5TR.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "5.1.0";
+var version = "5.2.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-OT57IOWN.js";
+} from "./chunk-N2LLD5TR.js";
 export {
   VERSION
 };

package/dist/docs/api/02-config.md

@@ -968,6 +968,57 @@ Enable tools like Claude, ChatGPT, GitHub Copilot, and Cursor to quickly underst
 See the [LLMs documentation](/docs/development/ask-your-architecture/llms.txt) for more information, how you can use it and examples.
 
 
+### `exports.html` {#exports.html}
+
+<AddedIn version="5.1.0" />
+
+- Type: `object`
+- Default: `{ enabled: true }` (`false` when your catalog uses authentication)
+
+Controls the [architecture reference](/docs/development/export/architecture-reference): your whole catalog as one HTML file, written to `architecture.html` in your build output on every build.
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  exports: {
+    html: {
+      enabled: false, // default is true
+    },
+  },
+};
+```
+
+Catalogs with authentication only get the reference when `enabled` is `true`, because files in the build output are served without the authentication checks.
+
+### `exports.custom` {#exports.custom}
+
+<AddedIn version="5.2.0" />
+
+- Type: `object`
+- Default: `{ enabled: true }` (`false` when your catalog uses authentication)
+
+Controls [custom exports](/docs/development/export/custom-exports) (see the [reference](/docs/development/export/reference#exports-custom)): the parts of your catalog you choose for partners, a regulator or another team, each written to `exports/<id>.html` in your build output on every build. Custom exports are only written when your catalog has custom export files.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` | Write the custom exports when you build. |
+| `dir` | `string` | The folder with your custom export files. Defaults to `exports`. |
+| `only` | `string[]` | Build only these custom exports, by id. |
+| `defaults.hide` | `string[]` | The fields every custom export leaves out, unless it sets its own `hide`. Defaults to `['owners', 'repository', 'contacts', 'docs']`. |
+| `defaults.references` | `string` | What every custom export shows for links to resources outside it, unless it sets its own: `omit` (the default), `name-only` or `include`. |
+| `neverExport` | `object[]` | Resources no custom export may show, whatever it includes. Takes [selectors](/docs/development/export/reference#selectors), by id or by custom property. |
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  exports: {
+    custom: {
+      only: ['partner-payments'],
+      defaults: { references: 'name-only' },
+      neverExport: [{ service: 'fraud-detection' }, { 'x-internal': true }],
+    },
+  },
+};
+```
+
 ### `fullCatalogAPIEnabled` {#fullCatalogAPIEnabled}
 
 <AddedIn version="3.10.2" />

package/dist/docs/development/bring-your-own-documentation/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Bring your own documentation",
-  "position": 5,
+  "position": 4.3,
   "collapsible": true,
   "collapsed": false,
   "link": {

package/dist/docs/development/customization/08-custom-properties.md

@@ -167,10 +167,57 @@ const { tier, scrumMasters = [] } = Astro.props;
 
 Read [Pass data into components](/docs/development/components/custom-components/pass-data-into-components) to learn more about using resource frontmatter with your own components.
 
+## Choose what goes in a custom export
+
+<AddedIn version="5.2.0" />
+
+[Custom exports](/docs/development/export/custom-exports) are parts of your catalog exported for people outside your teams. Their `include` and `exclude` can match resources by custom property, so resources can opt in (or out) from their own frontmatter:
+
+```mdx title="exports/partners.mdx"
+---
+title: Acme for partners
+include:
+  - x-public: true
+exclude:
+  - x-data-classification: [confidential, restricted]
+---
+```
+
+The custom properties choose what's in the export, but they aren't shown in it. Read [custom exports](/docs/development/export/custom-exports#by-custom-property) for how values are matched.
+
+## Find resources by custom property
+
+Use `getResourcesByProperty` in the [SDK](/docs/sdk) to find the resources with a custom property, optionally with a given value:
+
+```js
+import utils from '@eventcatalog/sdk';
+
+const { getResourcesByProperty } = utils('/path/to/eventcatalog');
+
+// Everything with x-operational-tier
+await getResourcesByProperty('x-operational-tier');
+
+// The latest tier 1 services
+await getResourcesByProperty('x-operational-tier', { equals: 1, types: ['service'], latestOnly: true });
+
+// Resources classified as confidential or restricted
+await getResourcesByProperty('x-data-classification', { in: ['confidential', 'restricted'] });
+```
+
+Each result has the resource's `type`, `id`, `version`, the property's `value`, the `path` to its file, and whether it's the `latest` version. Values are compared as text (`1` matches `'1'`), and a list matches when any of its items does.
+
+The SDK reads your catalog's frontmatter once and keeps it in memory, so repeated lookups don't read any files.
+
+You can run it from the [CLI](/docs/cli) too:
+
+```bash
+npx @eventcatalog/cli getResourcesByProperty "x-operational-tier" '{"equals":1}'
+```
+
 ## Naming and security guidance
 
 - Use stable, descriptive names such as `x-operational-tier` or `x-data-classification`.
 - Consider an organization namespace, such as `x-acme-cost-centre`, when properties may be shared across tools.
 - Keep the meaning and expected value type consistent across resources.
 - Do not store secrets, credentials, or private tokens in custom properties. Resource frontmatter is catalog content and may be included in generated output.
-- Custom properties are stored and rendered, but EventCatalog does not automatically use them for relationships, diagrams, search behavior, or validation beyond the `x-*` naming requirement.
+- Custom properties are stored and rendered, but EventCatalog does not automatically use them for relationships, diagrams, search behavior, or validation beyond the `x-*` naming requirement. [Custom exports](/docs/development/export/custom-exports) use them only when an export's selectors name them.

package/dist/docs/development/export/01-introduction.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 1
+keywords:
+- Export EventCatalog
+- Export architecture documentation
+- Share architecture
+- Single HTML file
+- Partner documentation
+sidebar_label: Introduction
+title: Export your catalog
+description: Share your architecture with people who can't open your catalog, as one self-contained HTML file. Export all of it, or just the part someone needs.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="5.1.0" />
+
+Some people need to understand your architecture but can't open your catalog: a partner integrating with your services, an auditor, the team at a company you've acquired, a contractor without access to your network.
+
+Exporting your catalog gives them **one self-contained HTML file**. It doesn't need a server and there's nothing to sign in to, so you can attach it to an email, add it to a design review, keep it with an audit, or host it next to your catalog.
+
+![The overview of an architecture reference, listing the domains, systems and services in the sidebar and a summary of the catalog](./img/architecture-reference-overview.png)
+
+[See the export of our demo catalog](https://demo.eventcatalog.dev/architecture.html)
+
+## Two ways to export
+
+| | [Architecture reference](/docs/development/export/architecture-reference) | [Custom export](/docs/development/export/custom-exports) |
+| --- | --- | --- |
+| **What's in it** | Your whole catalog | The part of your catalog you choose, with your own introduction |
+| **Who it's for** | People who should see everything: your teams in a design review, an architecture audit, an AI agent | People who need part of it: partners, a regulator, the team taking over a domain |
+| **How you make it** | Nothing to set up | A file in your catalog's `exports` folder that says what's in it |
+| **Where it's written** | `architecture.html` | `exports/<id>.html` |
+
+You can have both: one reference, and as many custom exports as you have audiences.
+
+## What's in the file
+
+Both are the same kind of file:
+
+- **An overview**, with how many of each resource it documents (and, for a custom export, its title, who it's for and its introduction).
+- **A section for every resource**, with its summary, badges and documentation (including mermaid diagrams).
+- **Relationships on every section**: who produces and consumes a message, what a service sends and receives, which services read and write a data store, what lives inside a domain or system. Every relationship is a link.
+- **Message attributes** from your JSON Schema, Avro and Protobuf schemas, with an example payload, a TypeScript type and the raw schema.
+- **Your specifications** (OpenAPI, AsyncAPI and GraphQL), which readers can view and download.
+- **Flows**, step by step, with every resource each step touches.
+- **Search** across the file (press `⌘K` or `Ctrl+K`), a sidebar filter, and light and dark themes.
+
+Only the latest version of each resource is included. Resources marked as hidden are left out.
+
+![A message in an export, with its attributes, producers, consumers and an example payload](./img/architecture-reference-message.png)
+
+## Written on every build
+
+You don't have to remember to export anything. Every time you build your catalog, EventCatalog writes the reference and your custom exports to the build output:
+
+| File | Static build | [Server mode](/docs/development/deployment/build-ssr-mode) | Hosted at |
+| --- | --- | --- | --- |
+| Architecture reference | `dist/architecture.html` | `dist/client/architecture.html` | `/architecture.html` |
+| Custom exports | `dist/exports/<id>.html` | `dist/client/exports/<id>.html` | `/exports/<id>.html` |
+
+Because they're written from your catalog on every build, a link you shared last month still shows what's true today.
+
+To export without building your catalog, use the [`export` command](/docs/cli/cli-export) of the [EventCatalog CLI](/docs/cli):
+
+```bash
+# The whole catalog
+npx @eventcatalog/cli export --format html
+
+# One custom export
+npx @eventcatalog/cli export partner-payments
+```
+
+## Catalogs with authentication
+
+If your catalog uses [authentication](/docs/development/authentication/introduction), nothing is exported when you build unless you turn it on. Files in the build output are served without the authentication checks, so anyone who knows the URL could read them.
+
+To export anyway, set `exports.html.enabled` (for the reference) or `exports.custom.enabled` (for custom exports) to `true` in `eventcatalog.config.js`. You can always export with the CLI and share the file yourself.
+
+## Sharing an export
+
+Exports use the `title`, `organizationName` and `logo` from your `eventcatalog.config.js` file. When you share a link to a hosted export in Slack, Teams or on social media, the preview shows the catalog's name (or the export's title) and what it documents.
+
+Each file shows when it was generated.
+
+## Next steps
+
+- [Export your whole catalog](/docs/development/export/architecture-reference) as an architecture reference.
+- [Create a custom export](/docs/development/export/custom-exports) for partners, a regulator or another team.
+- See the [reference](/docs/development/export/reference) for every field, option and command.

package/dist/docs/development/export/02-architecture-reference.md

@@ -0,0 +1,74 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog architecture reference
+- Export architecture documentation
+- Single HTML file
+sidebar_label: Architecture reference
+title: Architecture reference
+description: Export your whole catalog as one self-contained HTML file, on every build or with the CLI.
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="5.1.0" />
+
+The architecture reference is your whole catalog in one HTML file. Every domain, system, service, message, channel, data store, flow, entity and team gets its own section, linked to everything it relates to.
+
+Use it for people who should see all of your architecture: your own teams in a design review, an architecture audit, or an AI agent that needs the full picture. For anyone who should see only part of it, [create a custom export](/docs/development/export/custom-exports) instead.
+
+[See the demo architecture reference](https://demo.eventcatalog.dev/architecture.html)
+
+## Get it on every build
+
+The reference is generated every time you build your catalog. You don't need to set anything up.
+
+```bash
+npm run build
+```
+
+It is written to `dist/architecture.html`, or to `dist/client/architecture.html` when your catalog [runs in server mode](/docs/development/deployment/build-ssr-mode). Wherever you host your catalog, the reference is available at `/architecture.html`.
+
+### Turn it off
+
+Set `exports.html.enabled` to `false` in your `eventcatalog.config.js` file:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  exports: {
+    html: {
+      enabled: false,
+    },
+  },
+};
+```
+
+### Catalogs with authentication
+
+If your catalog uses [authentication](/docs/development/authentication/introduction), the reference is **not** generated unless you turn it on. Files in the build output are served without the authentication checks, so anyone who knows the URL could read it.
+
+To generate it anyway, set `exports.html.enabled` to `true`.
+
+## Export it with the CLI
+
+Use the [`export` command](/docs/cli/cli-export) of the [EventCatalog CLI](/docs/cli) to export the reference on demand, without building the catalog. From the root of your catalog, run:
+
+```bash
+npx @eventcatalog/cli export --format html
+```
+
+This writes `architecture.html` and opens it in your browser.
+
+| Option | Description |
+| --- | --- |
+| `--output <path>` | Where to write the file. Defaults to `architecture.html` |
+| `--no-open` | Don't open the reference in your browser (useful in CI) |
+| `--dir <path>` | Path to your catalog, if you aren't running the command from it |
+
+For example, to export the reference in a CI pipeline and publish it as a build artifact:
+
+```bash
+npx @eventcatalog/cli export --format html --output reports/architecture.html --no-open
+```
+
+The file shows when it was generated, and the command to generate it again.