@aws/nx-plugin 0.100.0 → 0.101.0

package/generators.json

@@ -103,6 +103,20 @@
       "description": "Add a Strands Agent to a Python project",
       "metric": "g25"
     },
+    "py#strands-agent#mcp-connection": {
+      "factory": "./src/py/strands-agent/mcp-connection/generator",
+      "schema": "./src/py/strands-agent/mcp-connection/schema.json",
+      "description": "Connect a Python Strands Agent to an MCP server",
+      "metric": "g32",
+      "hidden": true
+    },
+    "py#strands-agent#react-connection": {
+      "factory": "./src/py/strands-agent/react-connection/generator",
+      "schema": "./src/py/strands-agent/react-connection/schema.json",
+      "description": "Connect a React website to a Python Strands Agent",
+      "metric": "g34",
+      "hidden": true
+    },
     "smithy#project": {
       "factory": "./src/smithy/project/generator",
       "schema": "./src/smithy/project/schema.json",
@@ -124,6 +138,13 @@
       "metric": "g23",
       "guidePages": ["terraform-project"]
     },
+    "ts#astro-docs": {
+      "factory": "./src/ts/astro-docs/generator",
+      "schema": "./src/ts/astro-docs/schema.json",
+      "description": "Generates an Astro + Starlight documentation site with localisation, snippets, blog, and optional automated documentation translation",
+      "metric": "g37",
+      "guidePages": ["astro-docs"]
+    },
     "ts#infra": {
       "factory": "./src/infra/app/generator",
       "schema": "./src/infra/app/schema.json",
@@ -196,13 +217,6 @@
       "description": "Add a Strands Agent to a TypeScript project",
       "metric": "g30"
     },
-    "ts#strands-agent#react-connection": {
-      "factory": "./src/ts/strands-agent/react-connection/generator",
-      "schema": "./src/ts/strands-agent/react-connection/schema.json",
-      "description": "Connect a React website to a TypeScript Strands Agent",
-      "metric": "g33",
-      "hidden": true
-    },
     "ts#strands-agent#mcp-connection": {
       "factory": "./src/ts/strands-agent/mcp-connection/generator",
       "schema": "./src/ts/strands-agent/mcp-connection/schema.json",
@@ -210,11 +224,11 @@
       "metric": "g31",
       "hidden": true
     },
-    "py#strands-agent#mcp-connection": {
-      "factory": "./src/py/strands-agent/mcp-connection/generator",
-      "schema": "./src/py/strands-agent/mcp-connection/schema.json",
-      "description": "Connect a Python Strands Agent to an MCP server",
-      "metric": "g32",
+    "ts#strands-agent#react-connection": {
+      "factory": "./src/ts/strands-agent/react-connection/generator",
+      "schema": "./src/ts/strands-agent/react-connection/schema.json",
+      "description": "Connect a React website to a TypeScript Strands Agent",
+      "metric": "g33",
       "hidden": true
     },
     "ts#strands-agent#a2a-connection": {
@@ -231,13 +245,6 @@
       "metric": "g36",
       "hidden": true
     },
-    "py#strands-agent#react-connection": {
-      "factory": "./src/py/strands-agent/react-connection/generator",
-      "schema": "./src/py/strands-agent/react-connection/schema.json",
-      "description": "Connect a React website to a Python Strands Agent",
-      "metric": "g34",
-      "hidden": true
-    },
     "ts#sync": {
       "factory": "./src/ts/sync/generator",
       "schema": "./src/ts/sync/schema.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin",
-  "version": "0.100.0",
+  "version": "0.101.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/preset/__snapshots__/generator.spec.ts.snap

@@ -46,6 +46,8 @@ The following list of generators are what is currently available in the \`@aws/n
 
 - **terraform#project**: Generates a Terraform project
 
+- **ts#astro-docs**: Generates an Astro + Starlight documentation site with localisation, snippets, blog, and optional automated documentation translation
+
 - **ts#infra**: Generates a cdk application
 
 - **ts#lambda-function**: Generate a TypeScript lambda function

package/src/ts/astro-docs/__snapshots__/generator.spec.ts.snap

@@ -0,0 +1,223 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ts#astro-docs generator > should generate a docs site with default options (translation + blog enabled) > astro.config.mjs 1`] = `
+"// @ts-check
+import { defineConfig } from 'astro/config';
+
+import starlight from '@astrojs/starlight';
+import starlightBlog from 'starlight-blog';
+
+// https://astro.build/config
+export default defineConfig({
+  outDir: './dist',
+  // Redirect the root URL to the default locale so visitors land on localised content.
+  redirects: {
+    '/': '/en',
+  },
+  integrations: [
+    starlight({
+      title: 'docs',
+      social: [],
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 4,
+      },
+      defaultLocale: 'en',
+      locales: {
+        en: {
+          label: 'English',
+        },
+      },
+      sidebar: [
+        {
+          label: 'Getting started',
+          items: [{ slug: 'guides/getting-started' }],
+        },
+      ],
+      customCss: ['./src/styles/custom.css'],
+      plugins: [
+        starlightBlog({
+          authors: {
+            default: {
+              name: 'Docs Author',
+              title: 'Maintainer',
+            },
+          },
+        }),
+      ],
+    }),
+  ],
+});
+"
+`;
+
+exports[`ts#astro-docs generator > should generate a docs site with default options (translation + blog enabled) > index.mdx 1`] = `
+"---
+title: docs
+description: Documentation for docs.
+template: splash
+hero:
+  title: docs
+  tagline: Project documentation built with Astro and Starlight.
+  actions:
+    - text: Get started
+      link: /en/guides/getting-started
+      icon: right-arrow
+---
+
+import { CardGrid, Card } from '@astrojs/starlight/components';
+
+<CardGrid>
+  <Card title="Guides" icon="open-book">
+    Reference documentation for docs.
+  </Card>
+  <Card title="Blog" icon="pencil">
+    News and updates from the team.
+  </Card>
+  <Card title="Snippets" icon="seti:config">
+    Reusable content fragments used across the docs.
+  </Card>
+  <Card title="Localised" icon="translate">
+    Localisation is configured out of the box — add target locales in
+    \`astro.config.mjs\`.
+  </Card>
+</CardGrid>
+"
+`;
+
+exports[`ts#astro-docs generator > should generate a docs site with default options (translation + blog enabled) > link.astro 1`] = `
+"---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { LinkButton } from '@astrojs/starlight/components';
+
+// Resolve an internal docs path against the current locale so a single source of
+// truth (the \`path\` prop) produces a correct URL in every language. Callers pass
+// a locale-agnostic path like \`guides/getting-started\`.
+const { path, type } = Astro.props;
+let resolvedPath = getRelativeLocaleUrl(Astro.currentLocale || 'en', path);
+if (resolvedPath.endsWith('/')) {
+  resolvedPath = resolvedPath.slice(0, -1);
+}
+---
+
+{
+  type === 'button' ? (
+    <LinkButton href={resolvedPath}>
+      <slot />
+    </LinkButton>
+  ) : (
+    <a href={resolvedPath}>
+      <slot />
+    </a>
+  )
+}
+"
+`;
+
+exports[`ts#astro-docs generator > should generate a docs site with default options (translation + blog enabled) > project.json 1`] = `
+"{
+  "name": "@proj/docs",
+  "$schema": "../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "docs/src",
+  "projectType": "application",
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "astro build",
+        "cwd": "docs"
+      },
+      "outputs": ["{workspaceRoot}/docs/dist"],
+      "cache": true
+    },
+    "start": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "astro dev",
+        "cwd": "docs"
+      },
+      "continuous": true
+    },
+    "serve": {
+      "dependsOn": ["start"]
+    },
+    "preview": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "astro preview",
+        "cwd": "docs"
+      },
+      "dependsOn": ["build"],
+      "continuous": true
+    },
+    "translate": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsx ./scripts/translate.ts",
+        "cwd": "docs",
+        "forwardAllArgs": true
+      }
+    }
+  },
+  "metadata": {
+    "generator": "ts#astro-docs",
+    "includeTranslation": true,
+    "includeBlog": true
+  }
+}
+"
+`;
+
+exports[`ts#astro-docs generator > should generate a docs site with default options (translation + blog enabled) > snippet.astro 1`] = `
+"---
+import { Aside } from '@astrojs/starlight/components';
+
+const locale = Astro.currentLocale || 'en';
+const snippets = Object.values(
+  import.meta.glob('../content/docs/*/snippets/**/*.mdx', { eager: true })
+);
+const { name } = Astro.props;
+const snippet = snippets.find((s) =>
+  s.file.endsWith(\`content/docs/\${locale}/snippets/\${name}.mdx\`)
+);
+---
+
+{
+  snippet ? (
+    <snippet.Content />
+  ) : (
+    <Aside type="danger">Unable to load snippet {name} for locale {locale}</Aside>
+  )
+}
+"
+`;
+
+exports[`ts#astro-docs generator > should generate a docs site with default options (translation + blog enabled) > translate.config.json 1`] = `
+"{
+  "sourceLanguage": "en",
+  "targetLanguages": [],
+  "docsDir": "src/content/docs",
+  "include": ["**/*.md", "**/*.mdx"],
+  "exclude": [],
+  "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+  "awsRegion": "us-west-2",
+  "concurrency": 5
+}
+"
+`;
+
+exports[`ts#astro-docs generator > should generate a docs site with default options (translation + blog enabled) > tsconfig.json 1`] = `
+"{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@components/*": ["src/components/*"],
+      "@assets/*": ["src/content/docs/assets/*"]
+    }
+  }
+}
+"
+`;

package/src/ts/astro-docs/files/base/README.md.template

@@ -0,0 +1,63 @@
+# <%= fullyQualifiedName %>
+
+Documentation site generated with [@aws/nx-plugin](https://github.com/awslabs/nx-plugin-for-aws/),
+powered by [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/).
+
+## Run locally
+
+```bash
+<%= pkgMgrCmd %> nx start <%= fullyQualifiedName %>
+```
+
+## Build for production
+
+```bash
+<%= pkgMgrCmd %> nx build <%= fullyQualifiedName %>
+```
+
+## Preview the production build
+
+```bash
+<%= pkgMgrCmd %> nx preview <%= fullyQualifiedName %>
+```
+<% if (includeTranslation) { %>
+## Translate documentation
+
+This project is pre-wired with a translation script that uses a
+[Strands Agent](https://strandsagents.com/) powered by Claude on
+[Amazon Bedrock](https://aws.amazon.com/bedrock/) to translate documentation from
+the source language (`en` by default) into every locale listed in
+`scripts/translate.config.json`.
+
+By default the `targetLanguages` list is empty — add the locale codes you want
+to ship, for example:
+
+```json
+"targetLanguages": ["fr", "de", "es", "ja", "ko"]
+```
+
+Make sure each locale you list is also configured in `astro.config.mjs` under
+`locales`.
+
+Run the translator manually with:
+
+```bash
+<%= pkgMgrCmd %> nx translate <%= fullyQualifiedName %> -- --all
+```
+
+Translate only the files that changed since the last `docs: update translations`
+commit:
+
+```bash
+<%= pkgMgrCmd %> nx translate <%= fullyQualifiedName %>
+```
+
+Other options in `scripts/translate.config.json`:
+
+- `include` / `exclude` — glob patterns for docs files, relative to the source
+  language directory.
+- `modelId` — Bedrock model id.
+- `awsRegion` — Bedrock region; can be overridden with the `AWS_REGION` env var.
+- `concurrency` — cap on concurrent Bedrock requests (one agent per file ×
+  target language).
+<% } %>

package/src/ts/astro-docs/files/base/astro.config.mjs.template

@@ -0,0 +1,47 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+
+import starlight from '@astrojs/starlight';
+<% if (includeBlog) { %>import starlightBlog from 'starlight-blog';
+<% } %>
+// https://astro.build/config
+export default defineConfig({
+  outDir: './dist',
+  // Redirect the root URL to the default locale so visitors land on localised content.
+  redirects: {
+    '/': '/en',
+  },
+  integrations: [
+    starlight({
+      title: '<%= title %>',
+      social: [],
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 4,
+      },
+      defaultLocale: 'en',
+      locales: {
+        en: {
+          label: 'English',
+        },
+      },
+      sidebar: [
+        {
+          label: 'Getting started',
+          items: [{ slug: 'guides/getting-started' }],
+        },
+      ],
+      customCss: ['./src/styles/custom.css'],
+      plugins: [<% if (includeBlog) { %>
+        starlightBlog({
+          authors: {
+            default: {
+              name: 'Docs Author',
+              title: 'Maintainer',
+            },
+          },
+        }),
+      <% } %>],
+    }),
+  ],
+});

package/src/ts/astro-docs/files/base/src/components/link.astro.template

@@ -0,0 +1,25 @@
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { LinkButton } from '@astrojs/starlight/components';
+
+// Resolve an internal docs path against the current locale so a single source of
+// truth (the `path` prop) produces a correct URL in every language. Callers pass
+// a locale-agnostic path like `guides/getting-started`.
+const { path, type } = Astro.props;
+let resolvedPath = getRelativeLocaleUrl(Astro.currentLocale || 'en', path);
+if (resolvedPath.endsWith('/')) {
+  resolvedPath = resolvedPath.slice(0, -1);
+}
+---
+
+{
+  type === 'button' ? (
+    <LinkButton href={resolvedPath}>
+      <slot />
+    </LinkButton>
+  ) : (
+    <a href={resolvedPath}>
+      <slot />
+    </a>
+  )
+}

package/src/ts/astro-docs/files/base/src/components/snippet.astro.template

@@ -0,0 +1,20 @@
+---
+import { Aside } from '@astrojs/starlight/components';
+
+const locale = Astro.currentLocale || 'en';
+const snippets = Object.values(
+  import.meta.glob('../content/docs/*/snippets/**/*.mdx', { eager: true })
+);
+const { name } = Astro.props;
+const snippet = snippets.find((s) =>
+  s.file.endsWith(`content/docs/${locale}/snippets/${name}.mdx`)
+);
+---
+
+{
+  snippet ? (
+    <snippet.Content />
+  ) : (
+    <Aside type="danger">Unable to load snippet {name} for locale {locale}</Aside>
+  )
+}

package/src/ts/astro-docs/files/base/src/content/docs/en/blog/welcome.mdx.template

@@ -0,0 +1,13 @@
+---
+title: Welcome to <%= title %>
+date: <%= today %>
+authors:
+  - default
+---
+
+Welcome to the **<%= title %>** blog! This post was scaffolded by the
+`ts#astro-docs` generator.
+
+The blog is powered by the [`starlight-blog`](https://starlight-blog-docs.vercel.app/)
+plugin. Add new entries as MDX files under `src/content/docs/<locale>/blog/` with
+`title`, `date` and `authors` frontmatter.

package/src/ts/astro-docs/files/base/src/content/docs/en/guides/getting-started.mdx.template

@@ -0,0 +1,64 @@
+---
+title: Getting started
+description: Running your new Astro + Starlight docs site.
+---
+
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+
+Welcome to **<%= title %>**! This site is built with [Astro](https://astro.build/) and the
+[Starlight](https://starlight.astro.build/) documentation theme.
+
+## Run locally
+
+```bash
+<%= pkgMgrCmd %> nx start <%= fullyQualifiedName %>
+```
+
+## Build for production
+
+```bash
+<%= pkgMgrCmd %> nx build <%= fullyQualifiedName %>
+```
+
+## Adding a locale
+
+Add an entry to the `locales` block in `astro.config.mjs` and create a matching
+directory under `src/content/docs/<locale>/`. Starlight will pick up the new locale
+automatically.
+<% if (includeTranslation) { %>
+:::note[Keep the translation config in sync]
+When you add a new locale, also add its code to `targetLanguages` in
+`scripts/translate.config.json` so the `translate` task will keep it up to date.
+:::
+<% } %>
+## Locale-aware links
+
+Use the generated `Link` component whenever you want to link to another page
+**inside** your docs — it automatically resolves the current locale, so a single
+source of truth produces the right URL in every language:
+
+```mdx
+import Link from '@components/link.astro';
+
+<Link path="guides/getting-started">Read the getting-started guide</Link>
+```
+
+Here is the component in action: <Link path="guides/getting-started">back to this page</Link>.
+
+For regular external links, just use ordinary Markdown `[label](url)`.
+
+## Using snippets
+
+Snippets are reusable fragments of MDX stored in `src/content/docs/<locale>/snippets/`.
+Include one in any page with the `Snippet` component:
+
+```mdx
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="example" />
+```
+
+Here is the example snippet rendered inline:
+
+<Snippet name="example" />

package/src/ts/astro-docs/files/base/src/content/docs/en/index.mdx.template

@@ -0,0 +1,29 @@
+---
+title: <%= title %>
+description: Documentation for <%= title %>.
+template: splash
+hero:
+  title: <%= title %>
+  tagline: Project documentation built with Astro and Starlight.
+  actions:
+    - text: Get started
+      link: /en/guides/getting-started
+      icon: right-arrow
+---
+
+import { CardGrid, Card } from '@astrojs/starlight/components';
+
+<CardGrid>
+  <Card title="Guides" icon="open-book">
+    Reference documentation for <%= title %>.
+  </Card>
+  <Card title="Blog" icon="pencil">
+    News and updates from the team.
+  </Card>
+  <Card title="Snippets" icon="seti:config">
+    Reusable content fragments used across the docs.
+  </Card>
+  <Card title="Localised" icon="translate">
+    Localisation is configured out of the box — add target locales in `astro.config.mjs`.
+  </Card>
+</CardGrid>

package/src/ts/astro-docs/files/base/src/content/docs/en/snippets/example.mdx.template

@@ -0,0 +1,7 @@
+---
+title: Example snippet
+---
+
+This is an **example snippet**. Snippets are reusable fragments of MDX stored
+under `src/content/docs/<locale>/snippets/`. Import them into any page with the
+`<Snippet />` component.

package/src/ts/astro-docs/files/base/src/content.config.ts.template

@@ -0,0 +1,13 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+import { blogSchema } from 'starlight-blog/schema';
+
+export const collections = {
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({
+      extend: (context) => blogSchema(context),
+    }),
+  }),
+};

package/src/ts/astro-docs/files/base/src/styles/custom.css.template

@@ -0,0 +1 @@
+/* Customise the appearance of the Starlight docs theme here. */

package/src/ts/astro-docs/files/base/tsconfig.json.template

@@ -0,0 +1,12 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@components/*": ["src/components/*"],
+      "@assets/*": ["src/content/docs/assets/*"]
+    }
+  }
+}

package/src/ts/astro-docs/files/translation/scripts/translate.config.json.template

@@ -0,0 +1,10 @@
+{
+  "sourceLanguage": "en",
+  "targetLanguages": [],
+  "docsDir": "src/content/docs",
+  "include": ["**/*.md", "**/*.mdx"],
+  "exclude": [],
+  "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+  "awsRegion": "us-west-2",
+  "concurrency": 5
+}