@eventcatalog/core 4.12.0-beta.8 → 4.12.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 = "4.12.0-beta.8";
+var version = "4.12.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-WR5Q4QXI.js";
-import "../chunk-5HXYLZWD.js";
+} from "../chunk-SQXIGSIJ.js";
+import "../chunk-MZ5QBEFA.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

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

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-3ZWYGVW6.js";
+} from "../chunk-UC3HZHW4.js";
 import "../chunk-ZAZHAVKB.js";
-import "../chunk-WR5Q4QXI.js";
-import "../chunk-5HXYLZWD.js";
+import "../chunk-SQXIGSIJ.js";
+import "../chunk-MZ5QBEFA.js";
 import "../chunk-RFIXKATC.js";
 export {
   log_build_default as default

package/dist/{chunk-AP3ENLC2.js → chunk-DWTU2R2Z.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-2VXWWWTT.js";
+} from "./chunk-Q46W7LGT.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-5HXYLZWD.js → chunk-MZ5QBEFA.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "4.12.0-beta.8";
+var version = "4.12.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-2VXWWWTT.js → chunk-Q46W7LGT.js}

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

package/dist/{chunk-WR5Q4QXI.js → chunk-SQXIGSIJ.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-5HXYLZWD.js";
+} from "./chunk-MZ5QBEFA.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-3ZWYGVW6.js → chunk-UC3HZHW4.js}

@@ -5,7 +5,7 @@ import {
 } from "./chunk-ZAZHAVKB.js";
 import {
   raiseEvent
-} from "./chunk-WR5Q4QXI.js";
+} from "./chunk-SQXIGSIJ.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/constants.cjs

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

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-5HXYLZWD.js";
+} from "./chunk-MZ5QBEFA.js";
 export {
   VERSION
 };

package/dist/docs/development/01-getting-started/develop-and-build.md

@@ -24,6 +24,24 @@ npm run dev
 ```
 If all goes well, EventCatalog will now be serving your project on http://localhost:3000/. Visit that link in your browser and see your new site!
 
+### Clear the development cache
+
+<AddedIn version="4.12.0" />
+
+EventCatalog runs directly in your project and keeps generated files, such as content caches, types, and runtime metadata, in the `.astro/` folder.
+
+If the development server shows stale content, start it with `--force-recreate`. This clears and regenerates the whole `.astro/` folder.
+
+```bash
+npx eventcatalog dev --force-recreate
+```
+
+Keep `.astro/` in your `.gitignore` and `.dockerignore` files. New catalogs created with `create-eventcatalog` include it in both.
+
+:::info Upgrading from an older version?
+Before 4.12, EventCatalog copied itself into a `.eventcatalog-core/` folder in your project. EventCatalog no longer creates this folder. Once any older EventCatalog processes have stopped, you can delete it. `eventcatalog dev` and `eventcatalog build` tell you when the folder is safe to delete.
+:::
+
 ## Build and preview your catalog
 
 To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command in your terminal:

package/dist/docs/development/ask-your-architecture/02-eventcatalog-assistant/02-configuration.md

@@ -52,6 +52,10 @@ _Example of installing the OpenAI model:_
 npm install @ai-sdk/openai
 ```
 
+:::info AI SDK version
+From EventCatalog 4.12, the assistant uses [AI SDK v7](https://ai-sdk.dev/). Install a provider package that supports AI SDK v7, for example `@ai-sdk/openai@^4`. If you have [custom tools](/docs/development/ask-your-architecture/eventcatalog-assistant/bring-your-own-tools) that use AI SDK v6 APIs, update them to the v7 equivalents.
+:::
+
 #### Configuring `eventcatalog.chat.js`
 
 This file will provide the model and any model configuration to EventCatalog.

package/dist/docs/development/components/components/27-code-group.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 7.1
+keywords:
+  - components
+  - code group
+  - code examples
+sidebar_label: CodeGroup
+title: CodeGroup
+description: Show the same code example in several languages or files
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.11.0"/>
+
+The `<CodeGroup />` component groups several fenced code blocks into one panel. Readers switch between them with tabs or a dropdown, and copy the one they need.
+
+Use it when the same example exists in more than one language, or when an example is split across several files.
+
+![CodeGroup in dropdown mode, showing a TypeScript example with a language picker for TypeScript, Python, Java, C#, and Go](./img/code-group-dropdown.png)
+
+**Example**
+
+Wrap your code blocks in `<CodeGroup>`. The text after the language becomes the label for each block.
+
+````mdx title="/events/OrderCreated/index.mdx"
+<CodeGroup>
+
+```ts publish.ts
+await client.publish('OrderCreated', order);
+```
+
+```python publish.py
+client.publish("OrderCreated", order)
+```
+
+</CodeGroup>
+````
+
+Leave a blank line after the opening tag and before the closing tag, so the code blocks are parsed as Markdown.
+
+### Output
+
+![CodeGroup with TypeScript and Python tabs, shown next to an explanation using Columns](./img/columns-code-group.png)
+
+### Labels
+
+Each code block needs a label. EventCatalog picks it in this order:
+
+1. A `title` in the code fence, for example ` ```ts title="publish.ts" `
+1. The first word after the language, for example ` ```ts publish.ts `
+1. The language, for example `ts`
+
+EventCatalog also shows an icon for the language of each block, for example TypeScript, Python, Java, Go, C#, or JSON.
+
+When a reader picks a block, every other code group on the page with a block of the same label switches too. If a page has several examples that each include `publish.py`, choosing Python once shows Python everywhere.
+
+### Use a dropdown
+
+Tabs work well for two or three blocks. For more, add `dropdown` to show a language picker instead.
+
+````mdx title="/events/OrderCreated/index.mdx"
+<CodeGroup dropdown>
+
+```javascript publish-order.js
+await client.publish("OrderCreated", order);
+```
+
+```python publish_order.py
+client.publish("OrderCreated", order)
+```
+
+```java PublishOrder.java
+client.publish("OrderCreated", order);
+```
+
+```csharp PublishOrder.cs
+await client.PublishAsync("OrderCreated", order);
+```
+
+</CodeGroup>
+````
+
+### Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `dropdown` | `boolean` | `false` | Show a dropdown to switch between code blocks instead of tabs. |
+| `className` | `string` | | Extra CSS classes for the group. |
+
+### Support
+
+The `<CodeGroup />` component is supported in domains, systems, services, all messages, flows, changelogs, custom documentation pages, and [message usage examples](/docs/development/guides/resources/messages/add-usage-examples).
+
+Pair it with [`<Columns />`](/docs/development/components/components/columns) to show code next to the text that explains it.

package/dist/docs/development/components/components/28-columns.md

@@ -0,0 +1,115 @@
+---
+sidebar_position: 7.2
+keywords:
+  - components
+  - columns
+  - layout
+sidebar_label: Columns
+title: Columns
+description: Place content side by side in your EventCatalog pages
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="4.11.0"/>
+
+The `<Columns />` component places content side by side. Each `<Column />` inside it is one column.
+
+A common use is to put an explanation on the left and the code it describes on the right.
+
+**Example**
+
+````mdx title="/events/OrderCreated/index.mdx"
+<Columns cols={2}>
+
+  <Column>
+
+    ## Publish a review
+
+    Publish the event after the review is stored.
+
+  </Column>
+
+  <Column>
+
+    <CodeGroup>
+
+      ```ts publish.ts
+      await client.publish('ReviewSubmitted', review);
+      ```
+
+      ```python publish.py
+      client.publish("ReviewSubmitted", review)
+      ```
+
+    </CodeGroup>
+
+  </Column>
+
+</Columns>
+````
+
+Leave a blank line after each opening tag and before each closing tag, so the content inside is parsed as Markdown.
+
+### Output
+
+![Two columns, with an explanation on the left and a code group on the right](./img/columns-code-group.png)
+
+### Set the column widths
+
+By default, every column has the same width. Use `ratio` to change that. The ratio needs one number per column.
+
+```mdx title="/events/OrderCreated/index.mdx"
+<Columns cols={2} ratio="2:1">
+
+  <Column>
+
+    This column is twice as wide as the next one.
+
+  </Column>
+
+  <Column>
+
+    This column is narrower.
+
+  </Column>
+
+</Columns>
+```
+
+If the ratio does not match the number of columns, EventCatalog uses equal widths.
+
+### Keep a column in view
+
+Add `sticky` to a column to keep it in view while the reader scrolls past a longer column next to it. This is useful for long explanations next to a short code sample.
+
+```mdx
+<Column sticky>
+
+  ...
+
+</Column>
+```
+
+On narrow screens, columns stack on top of each other and `sticky` has no effect.
+
+### Props
+
+**`<Columns />`**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `cols` | `number` | `2` | Number of columns, from 1 to 4. |
+| `ratio` | `string` | | Relative column widths, for example `"2:1"` or `"1:2:1"`. |
+| `className` | `string` | | Extra CSS classes for the columns. |
+
+**`<Column />`**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `sticky` | `boolean` | `false` | Keep the column in view while the page scrolls. |
+| `className` | `string` | | Extra CSS classes for the column. |
+
+### Support
+
+The `<Columns />` component is supported in domains, systems, services, all messages, flows, changelogs, custom documentation pages, and [message usage examples](/docs/development/guides/resources/messages/add-usage-examples).

package/dist/docs/development/customization/05-custom-pages-and-api-routes/02-create-a-custom-page.md

@@ -10,6 +10,7 @@ description: Add a custom Astro page to your EventCatalog.
 ---
 
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
+import AddedIn from '@site/src/components/MDX/AddedIn';
 
 This guide shows you how to add a custom page to your catalog.
 
@@ -172,6 +173,26 @@ const { id } = Astro.params;
 
 This page is available at `/custom/reports/:id`, for example `/custom/reports/orders`.
 
+## Render a full-width page
+
+<AddedIn version="4.12.0" />
+
+Custom pages get the same page padding as built-in pages. If your page needs the full width, for example a dashboard, pass `fullWidth` to the layout.
+
+```js title="pages/dashboard.astro"
+---
+import Layout from '@catalog/layouts/Layout.astro';
+---
+
+<Layout title="Dashboard" fullWidth>
+  <div class="h-full w-full">
+    <!-- Your full-width content -->
+  </div>
+</Layout>
+```
+
+See the [`Layout` props](/docs/development/customization/custom-pages-and-api-routes/reference#layout-props) for all options.
+
 ## Learn more
 
 Custom pages follow Astro's routing model. See the [Astro pages documentation](https://docs.astro.build/en/basics/astro-pages/) if you want to go deeper.

package/dist/docs/development/customization/05-custom-pages-and-api-routes/04-reference.md

@@ -103,6 +103,30 @@ Use these aliases in custom pages.
 | `@catalog/utils` | Stable catalog data helpers such as `getServices`, `getDomains`, and `getEvents`. |
 | `@catalog/components/*` | Components from your catalog's top-level `components` directory. |
 
+## `Layout` props
+
+`@catalog/layouts/Layout.astro` accepts these props.
+
+```js title="pages/reports.astro"
+---
+import Layout from '@catalog/layouts/Layout.astro';
+---
+
+<Layout title="Service reports" description="Operational views built from catalog data." sidebar={false}>
+  <h1>Service reports</h1>
+</Layout>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | | Page title. Required. |
+| `description` | `string` | | Page description used in the page metadata. |
+| `sidebar` | `boolean` | `true` | Show the resource sidebar (domains, services, messages). |
+| `showHeader` | `boolean` | `true` | Show the EventCatalog header (search and navigation). |
+| `fullWidth` | `boolean` | `false` | Render content edge-to-edge without EventCatalog's page padding. Added in 4.12.0. |
+
+By default, custom pages get the same page padding and theme text color as built-in pages, so they read well in light and dark mode. Set `fullWidth` when your page controls its own layout, for example a dashboard or an embedded tool. Full-width pages still inherit the theme text color.
+
 ## `@catalog/utils`
 
 Use `@catalog/utils` to read catalog resources from custom pages and API routes.

package/dist/docs/development/deployment/hosting-options.md

@@ -102,6 +102,14 @@ Then you can run the server with:
 docker run -p 3000:3000 eventcatalog-server
 ```
 
+:::warning Your `.env` file is included in the server image
+
+`COPY . .` copies your `.env` file into the image, so EventCatalog can read your license key and other keys (for example `OPENAI_API_KEY`) during the build and when the server runs.
+
+Anyone who can pull the image can read these keys. Only push the image to a private registry, and do not share it publicly.
+
+:::
+
 :::info "Why do I need a server to run EventCatalog?"
 
 Some features of EventCatalog require a server to run (e.g. [EventCatalog Chat](/features/ai-assistant) and [EventCatalog Authentication](/docs/development/authentication/introduction)).

package/dist/docs/development/guides/resources/messages/09-add-usage-examples.md

@@ -13,16 +13,16 @@ sidebar_position: 7
 import AddedIn from '@site/src/components/MDX/AddedIn';
 import ProjectTree from '@site/src/components/MDX/ProjectTree';
 
-EventCatalog lets you attach example payloads to any message (event, command, or query). This can help your team understand exactly how your schemas can be used
+EventCatalog lets you attach examples to any message (event, command, or query). This can help your team understand exactly how your schemas can be used
 in your architecture and provide them with real examples.
 
-Examples appear in the Schema Explorer under a **Usage Examples** tab alongside the schema, properties, and changelog tabs.
+Examples appear in the [Schema Explorer](/docs/development/guides/resources/schemas/explore-schemas/schema-explorer) under an **Examples** tab alongside the schema, properties, and version tabs.
 
-![Example](./imgs/examples.png)
+![Examples tab in the Schema Explorer showing a written example next to a code group with JavaScript, Python, Java, and C# snippets](./imgs/examples.png)
 
 ### Add examples
 
-Create an `examples/` folder inside your message directory and drop in any example files. EventCatalog supports any text-based format: JSON, YAML, XML, Protobuf, and more.
+Create an `examples/` folder inside your message directory and drop in any example files. EventCatalog supports any text-based format: JSON, YAML, XML, Protobuf, Markdown, MDX, and more.
 
 <ProjectTree
   items={[
@@ -54,7 +54,99 @@ Create an `examples/` folder inside your message directory and drop in any examp
   ]}
 />
 
-The **Usage Examples** tab appears automatically when at least one example file is present. No frontmatter changes are required.
+The **Examples** tab appears automatically when at least one example file is present. No frontmatter changes are required.
+
+All examples for a message are shown on the same tab, one after another, ordered by file path.
+
+### Write examples in Markdown or MDX
+
+<AddedIn version="4.11.0" />
+
+Raw payloads show consumers the shape of a message, but not how to use it. Write your examples in Markdown or MDX to explain the scenario, call out important fields, and show code in more than one language.
+
+<ProjectTree
+  items={[
+    {
+      name: 'OrderCreated',
+      type: 'folder',
+      defaultOpen: true,
+      children: [
+        { name: 'index.mdx' },
+        { name: 'schema.json' },
+        {
+          name: 'examples',
+          type: 'folder',
+          defaultOpen: true,
+          children: [{ name: 'index.mdx', highlight: true }],
+        },
+      ],
+    },
+  ]}
+/>
+
+Markdown and MDX examples are rendered as documentation, not as source code. Use [`<Columns />`](/docs/development/components/components/columns) to put the explanation next to the code, and [`<CodeGroup />`](/docs/development/components/components/code-group) to show the same example in several languages.
+
+:::info Other components
+On the schema page (`/schemas/{type}/{id}/{version}`), MDX examples can use any EventCatalog [component](/docs/components/list). The preview panel on the `/schemas/explorer` list only supports `<Columns />`, `<Column />`, and `<CodeGroup />`, and shows MDX examples that use other components as source.
+:::
+
+````mdx title="events/OrderCreated/examples/index.mdx"
+---
+summary: Publish OrderCreated from checkout.
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## Publish a single-item order
+
+Publish an order containing one T-shirt after checkout succeeds.
+
+### Payload details
+
+- `orderId` identifies the order; `customerId` identifies the customer.
+- `total` uses integer minor units; `currency` is `GBP`.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```javascript publish-order.js
+await client.publish("OrderCreated", {
+  orderId: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+  total: 4999,
+  currency: "GBP",
+});
+```
+
+```python publish_order.py
+client.publish("OrderCreated", {
+    "orderId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+    "total": 4999,
+    "currency": "GBP",
+})
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+````
+
+Markdown and MDX examples support these frontmatter fields. Both are optional.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `title` | `string` | Title for the example. When omitted, EventCatalog uses the first level-one heading, then the file name. |
+| `summary` | `string` | Short description shown above the example. |
+
+:::tip
+You can put every example in a single `examples/index.mdx` file, or split them across several files. Use a horizontal rule (`---`) between examples in the same file to separate them.
+:::
 
 ### Organise with subfolders
 
@@ -105,13 +197,15 @@ international-order.json:
   summary: An order with international shipping and customs information.
 ```
 
-All fields are optional. When `name` is omitted, EventCatalog uses the filename without its extension as the title.
+All fields are optional. When `name` is omitted, EventCatalog uses the filename without its extension.
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `name` | `string` | Display name shown in the examples list |
-| `summary` | `string` | Short description shown below the name |
-| `usage` | `string` | How-to-run snippet shown below the code block |
+| `name` | `string` | Display name for the example |
+| `summary` | `string` | Short description shown above the example |
+| `usage` | `string` | How-to-run snippet shown below the example |
+
+For Markdown and MDX examples, you can use frontmatter instead of the config file. Values in `examples.config.yaml` take precedence.
 
 ### Use the SDK
 

package/dist/docs/development/guides/resources/schemas/04-explore-schemas/01-schema-explorer.md

@@ -11,21 +11,22 @@ import AddedIn from '@site/src/components/MDX/AddedIn';
 
 The Schema Explorer lets your teams quickly find the schema, understand who owns it, and who is producing or consuming it (see [demo](https://demo.eventcatalog.dev/schemas)).
 
-![Example](../img/schema-explorer.png)
+![Schema Explorer with a list of schemas on the left and the Review Submitted schema open on the right](../img/schema-explorer.png)
 
 Using the Schema Explorer, you can:
 
 - Quickly find schemas in your Architecture
-- View diffs between versions of your schemas
-- Quickly find who is consuming or producing your schemas
-- Schema ownership to query who owns a schema
+- Read usage examples written by the team that owns the schema
+- See who is producing or consuming a schema, and which flows it is part of
+- Compare versions of your schemas
+- See schema ownership and where the schema comes from
 - Get API (GET) access to your schemas for mocking or testing
 
 ### How to use the Schema Explorer?
 
 You can access the Schema Explorer from the sidebar, or by going to the `/schemas/explorer` page.
 
-The page will take all the schemas from your EventCatalog and render them in a searchable list.
+The page will take all the schemas from your EventCatalog and render them in a searchable list. Select a schema to open it on the right.
 
 :::tip Schema Path
 You need to set the `schemaPath` in your schema frontmatter to the path to your schema file for Events, Queries and Commands.
@@ -33,19 +34,84 @@ You need to set the `schemaPath` in your schema frontmatter to the path to your
 For services you need to specify the path to your specification file in the `specifications` frontmatter.
 :::
 
-![Example](../img/schema-explorer-2.png)
-
 ##### Filters
-You can use the filters to quickly find schemas in your Architecture. You can filter by name, message type and schema format.
 
-##### Schema Preview
+Use the search box to find schemas by name. Select the filter button next to it to filter by type (events, commands, queries, or specifications) and by schema format.
 
-The schema preview will show you a preview of the schema in a readable format, you can use the `Schema` button to switch between different views of your schema (if they are supported, JSON or Avro).
+<img src={require('../img/schema-explorer-2.png').default} alt="Schema Explorer search box and filters for type and format" style={{ width: '100%', maxWidth: '360px' }} />
 
-##### API Access
+##### Schema pages
+
+Every message schema also has its own page at `/schemas/{type}/{id}/{version}`, for example `/schemas/events/OrderCreated/1.0.0`. Share this link when you want someone to look at one schema.
+
+### Schema tabs
+
+<AddedIn version="4.11.0" />
+
+Each schema is split into tabs. EventCatalog only shows a tab when there is something to show, for example the **Flows** tab only appears when the message is part of a flow.
+
+| Tab | What it shows |
+| --- | ------------- |
+| **Schema** | The raw schema, with syntax highlighting and a copy button. |
+| **Properties** | A readable view of the schema properties (JSON Schema, Avro and Protobuf). |
+| **Examples** | [Usage examples](/docs/development/guides/resources/messages/add-usage-examples) stored in the message's `examples/` folder. |
+| **Producers & Consumers** | A graph of the services that produce and consume the message. |
+| **Flows** | The [flows](/docs/development/guides/resources/flows/introduction) the message is part of. |
+| **Versions** | Every version of the schema, with a side-by-side comparison. |
+| **Details** | Schema metadata: format, version, file, source, and owners. |
+| **API** | API access to the schema (EventCatalog Scale). |
+
+##### Link to a tab
+
+The selected tab is stored in the `tab` query parameter, so you can link straight to it.
+
+```txt
+/schemas/events/OrderCreated/1.0.0?tab=examples
+```
+
+| Tab | `tab` value |
+| --- | ----------- |
+| Schema | `schema` (default) |
+| Properties | `properties` |
+| Examples | `examples` |
+| Producers & Consumers | `producers-consumers` |
+| Flows | `flows` |
+| Versions | `versions` |
+| Details | `details` |
+| API | `api` |
+
+If the tab does not exist for that message, EventCatalog opens the **Schema** tab.
+
+##### Examples
+
+The **Examples** tab shows the examples your team has written for the message. Examples written in Markdown or MDX can explain the scenario and show code in several languages.
 
-For EventCatalog Scale users, you can get API (GET) access to your schemas for mocking or testing. 
+![Examples tab showing a written example next to a code group](../img/schema-explorer-examples.png)
+
+To add examples, see [Add usage examples](/docs/development/guides/resources/messages/add-usage-examples).
 
 ##### Producers and Consumers
 
-The producers and consumers section will show you who is producing or consuming the schema. You can click on the producer or consumer to see more information about them.
+The **Producers & Consumers** tab shows the services that produce and consume the message, using the same graph as the message page. Click on a producer or consumer to see more information about them.
+
+![Producers and Consumers tab showing the Review API publishing Review Submitted, which the Review Moderation Worker subscribes to](../img/schema-explorer-producers-consumers.png)
+
+##### Flows
+
+The **Flows** tab shows the flows the message is part of. If the message is used in more than one flow, pick the flow from the dropdown. Use **Open flow** to go to the flow page.
+
+![Flows tab showing the Review Submission flow](../img/schema-explorer-flows.png)
+
+##### Versions
+
+The **Versions** tab lists every version of the schema. Select a version to view it, or pick a **From** and **To** version to compare them side by side. Use **Expand** to open the comparison in a larger view.
+
+You can also switch versions from the version dropdown next to the schema name.
+
+##### Details
+
+The **Details** tab shows the schema name, format, message type, version, file, and owners. When a schema comes from an external source, the tab also shows where it came from.
+
+##### API Access
+
+For EventCatalog Scale users, you can get API (GET) access to your schemas for mocking or testing. See [Schema API](/docs/development/guides/resources/schemas/schema-api).

package/dist/docs/development/upgrading/upgrading.md

@@ -38,7 +38,11 @@ To upgrade your EventCatalog you can find the packages `@eventcatalog/core` your
 Once you upgrade the version number, run `npm install` to install the latest updates.
 
 :::tip
-If you don't see the changes you expect, try removing the `.eventcatalog-core` folder, `node_modules` folder and install fresh again.
+If you don't see the changes you expect, try removing the `.astro` folder, the `.eventcatalog-core` folder (if your project has one) and the `node_modules` folder, then install fresh again.
+:::
+
+:::info
+From EventCatalog 4.12, EventCatalog no longer creates a `.eventcatalog-core` folder. If your project still has one from an older version, you can delete it once any older EventCatalog processes have stopped.
 :::
 
 ### Having problems?
@@ -46,9 +50,10 @@ If you don't see the changes you expect, try removing the `.eventcatalog-core` f
 Trying to upgrade and having issues? Try these steps
 
 1. Delete `node_modules` folder
-1. Delete `.eventcatalog-core` folder
+1. Delete `.astro` folder
+1. Delete `.eventcatalog-core` folder (if you have one)
 1. Delete `package-lock.json` (if you have one).
-1. Run `npm run i`
+1. Run `npm install`
 1. Verify if issues are fixed
 
 Still having issues?

package/dist/docs/development/upgrading/v4.md

@@ -43,7 +43,7 @@ Before upgrading, we recommend:
 
 1. Create a branch for the upgrade.
 1. Upgrade `@eventcatalog/core`.
-1. Remove `.eventcatalog-core`, `node_modules`, and your lock file if the catalog does not pick up the new version.
+1. Remove `.astro`, `.eventcatalog-core` (if you have one), `node_modules`, and your lock file if the catalog does not pick up the new version.
 1. Run your catalog locally and check custom pages, custom navigation, and visualiser links.
 
 ## Removed

package/dist/eventcatalog.cjs

@@ -181,7 +181,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.12.0-beta.8";
+var version = "4.12.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.js

@@ -4,7 +4,7 @@ import {
 import "./chunk-CA4U2JP7.js";
 import {
   log_build_default
-} from "./chunk-3ZWYGVW6.js";
+} from "./chunk-UC3HZHW4.js";
 import "./chunk-ZAZHAVKB.js";
 import {
   FederationConflictError,
@@ -30,10 +30,10 @@ import {
 } from "./chunk-MDWB5HLO.js";
 import {
   generate
-} from "./chunk-AP3ENLC2.js";
+} from "./chunk-DWTU2R2Z.js";
 import {
   logger
-} from "./chunk-2VXWWWTT.js";
+} from "./chunk-Q46W7LGT.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-36RYTYT5.js";
@@ -47,7 +47,7 @@ import {
 import {
   watch
 } from "./chunk-U63GDPPY.js";
-import "./chunk-WR5Q4QXI.js";
+import "./chunk-SQXIGSIJ.js";
 import {
   getAstroConfigPath
 } from "./chunk-VIJJ7JKH.js";
@@ -63,7 +63,7 @@ import {
 } from "./chunk-LFQJXLHG.js";
 import {
   VERSION
-} from "./chunk-5HXYLZWD.js";
+} from "./chunk-MZ5QBEFA.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/generate.cjs

@@ -112,7 +112,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.12.0-beta.8";
+var version = "4.12.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-AP3ENLC2.js";
-import "./chunk-2VXWWWTT.js";
-import "./chunk-5HXYLZWD.js";
+} from "./chunk-DWTU2R2Z.js";
+import "./chunk-Q46W7LGT.js";
+import "./chunk-MZ5QBEFA.js";
 import "./chunk-RFIXKATC.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.12.0-beta.8";
+var version = "4.12.0";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-2VXWWWTT.js";
-import "../chunk-5HXYLZWD.js";
+} from "../chunk-Q46W7LGT.js";
+import "../chunk-MZ5QBEFA.js";
 export {
   logger
 };

package/eventcatalog/src/components/Badge.astro

@@ -17,75 +17,82 @@ type Badge = {
 };
 
 type Props = {
-  badge: Badge;
+  badge?: Badge | null;
   className?: string;
 };
 
 const { badge, className = '' } = Astro.props;
-const href = getBadgeHref(badge);
+const href = badge ? getBadgeHref(badge) : undefined;
 // Only links that leave the catalog get the external-link arrow.
 const isExternalHref = !!href && (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//'));
-const Icon = badge.icon || badge.iconComponent;
-const hasThemedIcon = badge.iconURLLight && badge.iconURLDark;
+const Icon = badge?.icon || badge?.iconComponent;
+const hasThemedIcon = Boolean(badge?.iconURLLight && badge?.iconURLDark);
+const badgeId = badge?.id || undefined;
+const content = badge?.content ?? '';
+const iconURL = badge?.iconURL;
+const iconURLLight = badge?.iconURLLight;
+const iconURLDark = badge?.iconURLDark;
+const style = badge ? getBadgeStyle(badge) : '';
 const classes = `
   inline-flex items-center gap-1 px-1.5 py-0.5 rounded-md text-xs font-medium
-  ${badge.backgroundColor ? 'bg-[rgb(var(--ec-content-hover))]' : 'bg-transparent'} border border-[rgb(var(--ec-page-border))]
+  ${badge?.backgroundColor ? 'bg-[rgb(var(--ec-content-hover))]' : 'bg-transparent'} border border-[rgb(var(--ec-page-border))]
   text-[rgb(var(--ec-page-text))]
   shadow-xs
-  ${badge.class ? badge.class : ''}
+  ${badge?.class ? badge.class : ''}
   ${className}
 `;
 ---
 
 {
-  href ? (
-    <a id={badge.id || undefined} href={href} class={classes} style={getBadgeStyle(badge)} title={badge.content}>
-      {Icon && <Icon className="w-3 h-3 flex-shrink-0" />}
-      {hasThemedIcon && (
-        <img
-          src={badge.iconURLLight}
-          class="w-3 h-3 flex-shrink-0 opacity-80 dark:hidden"
-          alt=""
-          onerror="this.style.display='none'"
-        />
-      )}
-      {hasThemedIcon && (
-        <img
-          src={badge.iconURLDark}
-          class="hidden w-3 h-3 flex-shrink-0 opacity-80 dark:inline-block"
-          alt=""
-          onerror="this.style.display='none'"
-        />
-      )}
-      {!hasThemedIcon && badge.iconURL && (
-        <img src={badge.iconURL} class="w-3 h-3 flex-shrink-0 opacity-80" alt="" onerror="this.style.display='none'" />
-      )}
-      <span>{badge.content}</span>
-      {isExternalHref && <ArrowTopRightOnSquareIcon className="w-2.5 h-2.5 flex-shrink-0 opacity-70" aria-hidden="true" />}
-    </a>
-  ) : (
-    <span id={badge.id || undefined} class={classes} style={getBadgeStyle(badge)} title={badge.content}>
-      {Icon && <Icon className="w-3 h-3 flex-shrink-0" />}
-      {hasThemedIcon && (
-        <img
-          src={badge.iconURLLight}
-          class="w-3 h-3 flex-shrink-0 opacity-80 dark:hidden"
-          alt=""
-          onerror="this.style.display='none'"
-        />
-      )}
-      {hasThemedIcon && (
-        <img
-          src={badge.iconURLDark}
-          class="hidden w-3 h-3 flex-shrink-0 opacity-80 dark:inline-block"
-          alt=""
-          onerror="this.style.display='none'"
-        />
-      )}
-      {!hasThemedIcon && badge.iconURL && (
-        <img src={badge.iconURL} class="w-3 h-3 flex-shrink-0 opacity-80" alt="" onerror="this.style.display='none'" />
-      )}
-      <span>{badge.content}</span>
-    </span>
-  )
+  badge &&
+    (href ? (
+      <a id={badgeId} href={href} class={classes} style={style} title={content}>
+        {Icon && <Icon className="w-3 h-3 flex-shrink-0" />}
+        {hasThemedIcon && (
+          <img
+            src={iconURLLight}
+            class="w-3 h-3 flex-shrink-0 opacity-80 dark:hidden"
+            alt=""
+            onerror="this.style.display='none'"
+          />
+        )}
+        {hasThemedIcon && (
+          <img
+            src={iconURLDark}
+            class="hidden w-3 h-3 flex-shrink-0 opacity-80 dark:inline-block"
+            alt=""
+            onerror="this.style.display='none'"
+          />
+        )}
+        {!hasThemedIcon && iconURL && (
+          <img src={iconURL} class="w-3 h-3 flex-shrink-0 opacity-80" alt="" onerror="this.style.display='none'" />
+        )}
+        <span>{content}</span>
+        {isExternalHref && <ArrowTopRightOnSquareIcon className="w-2.5 h-2.5 flex-shrink-0 opacity-70" aria-hidden="true" />}
+      </a>
+    ) : (
+      <span id={badgeId} class={classes} style={style} title={content}>
+        {Icon && <Icon className="w-3 h-3 flex-shrink-0" />}
+        {hasThemedIcon && (
+          <img
+            src={iconURLLight}
+            class="w-3 h-3 flex-shrink-0 opacity-80 dark:hidden"
+            alt=""
+            onerror="this.style.display='none'"
+          />
+        )}
+        {hasThemedIcon && (
+          <img
+            src={iconURLDark}
+            class="hidden w-3 h-3 flex-shrink-0 opacity-80 dark:inline-block"
+            alt=""
+            onerror="this.style.display='none'"
+          />
+        )}
+        {!hasThemedIcon && iconURL && (
+          <img src={iconURL} class="w-3 h-3 flex-shrink-0 opacity-80" alt="" onerror="this.style.display='none'" />
+        )}
+        <span>{content}</span>
+      </span>
+    ))
 }

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/_index.data.ts

@@ -1,4 +1,5 @@
 import { isSSR, isChangelogEnabled } from '@utils/feature';
+import { changelogResourceCollections } from '@utils/changelog-resource-badge';
 import { HybridPage } from '@utils/page-loaders/hybrid-page';
 import type { PageTypes } from '@types';
 
@@ -14,17 +15,7 @@ export class Page extends HybridPage {
 
     const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
 
-    const itemTypes: PageTypes[] = [
-      'agents',
-      'events',
-      'commands',
-      'queries',
-      'services',
-      'domains',
-      'systems',
-      'flows',
-      'containers',
-    ];
+    const itemTypes: PageTypes[] = [...changelogResourceCollections];
     const allItems = await Promise.all(itemTypes.map((type) => pageDataLoader[type]()));
 
     return allItems.flatMap((items, index) =>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/changelog/index.astro

@@ -1,15 +1,7 @@
 ---
 import Footer from '@layouts/Footer.astro';
 import { getChangeLogs } from '@utils/collections/changelogs';
-import {
-  RectangleGroupIcon,
-  ServerIcon,
-  BoltIcon,
-  ChatBubbleLeftIcon,
-  MagnifyingGlassIcon,
-  QueueListIcon,
-} from '@heroicons/react/24/outline';
-import { DatabaseIcon } from 'lucide-react';
+import { getChangelogResourceBadge } from '@utils/changelog-resource-badge';
 import { render, getEntry } from 'astro:content';
 import mdxComponents from '@components/MDX/components';
 import 'diff2html/bundles/css/diff2html.min.css';
@@ -20,7 +12,6 @@ import { getDiffsForCurrentAndPreviousVersion } from '@utils/file-diffs';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import Badge from '@components/Badge.astro';
 import { ClientRouter } from 'astro:transitions';
-import { isChangelogEnabled } from '@utils/feature';
 
 import { Page } from './_index.data';
 
@@ -72,33 +63,7 @@ const logListPromise = logsToRender.map(async (log, index) => {
 
 const logList = await Promise.all(logListPromise);
 
-const createResourceBadge = (content: string, icon: any) => ({ content, icon, textColor: 'gray' });
-
-const getBadge = () => {
-  if (props.collection === 'services') {
-    return createResourceBadge('Service', ServerIcon);
-  }
-  if (props.collection === 'events') {
-    return createResourceBadge('Event', BoltIcon);
-  }
-  if (props.collection === 'commands') {
-    return createResourceBadge('Command', ChatBubbleLeftIcon);
-  }
-  if (props.collection === 'queries') {
-    return createResourceBadge('Query', MagnifyingGlassIcon);
-  }
-  if (props.collection === 'domains') {
-    return createResourceBadge('Domain', RectangleGroupIcon);
-  }
-  if (props.collection === 'containers') {
-    return createResourceBadge('Container', DatabaseIcon);
-  }
-  if (props.collection === 'flows') {
-    return createResourceBadge('Flow', QueueListIcon);
-  }
-};
-
-const badges = [getBadge()];
+const badges = [getChangelogResourceBadge(props.collection)].filter((badge) => badge != null);
 ---
 
 <VerticalSideBarLayout title="ChangeLog">
@@ -140,9 +105,9 @@ const badges = [getBadge()];
         <h2 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{props.data.name} (Changelog)</h2>
         <h2 class="text-lg pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{props.data.summary}</h2>
         {
-          badges && (
+          badges.length > 0 && (
             <div class="flex flex-wrap py-2 pt-4">
-              {badges.map((badge: any) => (
+              {badges.map((badge) => (
                 <Badge badge={badge} className="mr-2 px-2 py-1 rounded-md" />
               ))}
             </div>
@@ -188,7 +153,7 @@ const badges = [getBadge()];
                   )}
                   {log.badges && (
                     <div class="flex flex-wrap">
-                      {log.badges.map((badge: any) => (
+                      {log.badges.filter(Boolean).map((badge: any) => (
                         <Badge badge={badge} className="mr-2 px-2 py-1 rounded-md" />
                       ))}
                     </div>

package/eventcatalog/src/utils/badge-styles.ts

@@ -201,7 +201,9 @@ const resolveBadgeColor = (color: string | undefined, kind: BadgeColorKind) => {
   return undefined;
 };
 
-export const getBadgeStyle = (badge: Badge) => {
+export const getBadgeStyle = (badge?: Badge | null) => {
+  if (!badge) return '';
+
   const backgroundColor = resolveBadgeColor(badge.backgroundColor, 'background');
   const color = resolveBadgeColor(badge.textColor, 'text');
 
@@ -210,7 +212,9 @@ export const getBadgeStyle = (badge: Badge) => {
     .join(' ');
 };
 
-export const getBadgeReactStyle = (badge: Badge) => {
+export const getBadgeReactStyle = (badge?: Badge | null) => {
+  if (!badge) return {};
+
   const backgroundColor = resolveBadgeColor(badge.backgroundColor, 'background');
   const color = resolveBadgeColor(badge.textColor, 'text');
 
@@ -220,8 +224,8 @@ export const getBadgeReactStyle = (badge: Badge) => {
   };
 };
 
-export const getBadgeHref = (badge: Badge) => {
-  if (!badge.url) return undefined;
+export const getBadgeHref = (badge?: Badge | null) => {
+  if (!badge?.url) return undefined;
 
   const url = badge.url.trim();
   if (!url) return undefined;

package/eventcatalog/src/utils/changelog-resource-badge.ts

@@ -0,0 +1,52 @@
+import {
+  BoltIcon,
+  ChatBubbleLeftIcon,
+  MagnifyingGlassIcon,
+  QueueListIcon,
+  RectangleGroupIcon,
+  ServerIcon,
+} from '@heroicons/react/24/outline';
+import { Bot, DatabaseIcon, Group } from 'lucide-react';
+import type { PageTypes } from '@types';
+
+export type ChangelogResourceBadge = {
+  content: string;
+  icon: any;
+  textColor: 'gray';
+};
+
+// Every collection that prerenders a changelog route needs a badge. A missing
+// entry used to return undefined and crash static builds in Badge.astro.
+export const changelogResourceCollections = [
+  'agents',
+  'events',
+  'commands',
+  'queries',
+  'services',
+  'domains',
+  'systems',
+  'flows',
+  'containers',
+] as const satisfies readonly PageTypes[];
+
+export type ChangelogResourceCollection = (typeof changelogResourceCollections)[number];
+
+const changelogResourceBadges: Record<ChangelogResourceCollection, ChangelogResourceBadge> = {
+  agents: { content: 'Agent', icon: Bot, textColor: 'gray' },
+  events: { content: 'Event', icon: BoltIcon, textColor: 'gray' },
+  commands: { content: 'Command', icon: ChatBubbleLeftIcon, textColor: 'gray' },
+  queries: { content: 'Query', icon: MagnifyingGlassIcon, textColor: 'gray' },
+  services: { content: 'Service', icon: ServerIcon, textColor: 'gray' },
+  domains: { content: 'Domain', icon: RectangleGroupIcon, textColor: 'gray' },
+  systems: { content: 'System', icon: Group, textColor: 'gray' },
+  flows: { content: 'Flow', icon: QueueListIcon, textColor: 'gray' },
+  containers: { content: 'Container', icon: DatabaseIcon, textColor: 'gray' },
+};
+
+export const isChangelogResourceCollection = (collection: string): collection is ChangelogResourceCollection =>
+  (changelogResourceCollections as readonly string[]).includes(collection);
+
+export const getChangelogResourceBadge = (collection: string): ChangelogResourceBadge | undefined => {
+  if (!isChangelogResourceCollection(collection)) return undefined;
+  return changelogResourceBadges[collection];
+};

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.12.0-beta.8",
+  "version": "4.12.0",
   "publishConfig": {
     "access": "public"
   },