awslabs · nx-plugin-for-aws · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026
diff --git a/docs/src/content/docs/en/blog/migrating-from-aws-pdk.mdx b/docs/src/content/docs/en/blog/migrating-from-aws-pdk.mdx
@@ -5,7 +5,7 @@ date: 2025-09-26
 authors:
  - jack
 ---
-import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+import { Steps } from '@astrojs/starlight/components';
 import Snippet from '@components/snippet.astro';
 import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
 import RunGenerator from '@components/run-generator.astro';
@@ -36,7 +36,7 @@ Note also that some features of PDK don't have exact equivalents. Refer to the [
 :::
 
 :::caution[Point-in-Time Guide]
-This is written as a point-of-time guide and will most likely not be updated as the Nx Plugin for AWS evolves. To compensate for this, the guide pins the version of `@aws/nx-plugin` to `0.50.0`. You can try with the latest version if following along, but there may be some deviations from the guide.
+This is written as a point-of-time guide and will most likely not be updated as the Nx Plugin for AWS evolves. To compensate for this, the guide pins the version of `@aws/nx-plugin` to `1.0.0-rc.10`. You can try with the latest version if following along, but there may be some deviations from the guide.
 :::
 
 ## Example Migration: Shopping List Application
@@ -54,28 +54,7 @@ The shopping list application consists of the following PDK project types:
 
 To start, we'll create a new workspace for our new project. While more extreme than an in-place migration, this approach gives us the cleanest end result. Creating an Nx workspace is equivalent to using PDK's `MonorepoTsProject`:
 
-<Tabs syncKey="cli-command">
-  <TabItem label="pnpm" icon="pnpm">
-    ```bash
-    npx create-nx-workspace@21.4.1 shopping-list --pm=pnpm --preset=@aws/nx-plugin@0.50.0 --iacProvider=CDK --ci=skip --analytics=false
-    ```
-  </TabItem>
-  <TabItem label="yarn" icon="seti:yarn">
-    ```bash
-    npx create-nx-workspace@21.4.1 shopping-list --pm=yarn --preset=@aws/nx-plugin@0.50.0 --iacProvider=CDK --ci=skip --analytics=false
-    ```
-  </TabItem>
-  <TabItem label="npm" icon="seti:npm">
-    ```bash
-    npx create-nx-workspace@21.4.1 shopping-list --pm=npm --preset=@aws/nx-plugin@0.50.0 --iacProvider=CDK --ci=skip --analytics=false
-    ```
-  </TabItem>
-  <TabItem label="bun" icon="bun">
-    ```bash
-    npx create-nx-workspace@21.4.1 shopping-list --pm=bun --preset=@aws/nx-plugin@0.50.0 --iacProvider=CDK --ci=skip --analytics=false
-    ```
-  </TabItem>
-</Tabs>
+<CreateNxWorkspaceCommand workspace="shopping-list" iac="cdk" tag="1.0.0-rc.10" />
 
 Open up the `shopping-list` directory this command creates in your favourite IDE.
 

diff --git a/docs/src/content/docs/en/snippets/pdk-migration/example/01-migrate-api.mdx b/docs/src/content/docs/en/snippets/pdk-migration/example/01-migrate-api.mdx
@@ -23,9 +23,9 @@ If you used OpenAPI or TypeSpec as your modelling language, or have handlers imp
 
 #### Generate a TypeScript Smithy API
 
-Run the <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link> to set up your api project in `packages/api`:
+Run the <Link path="/guides/ts-smithy-api">`ts#api` generator</Link> with `framework` set to `smithy` to set up your api project in `packages/api`:
 
-<RunGenerator generator="ts#smithy-api" noInteractive requiredParameters={{ name: 'api', namespace: 'com.aws', auth: 'IAM' }} />
+<RunGenerator generator="ts#api" noInteractive requiredParameters={{ name: 'api', framework: 'smithy', namespace: 'com.aws', auth: 'iam' }} />
 
 You will notice this generates a `model` project, as well as a `backend` project. The `model` project contains your Smithy model, and `backend` contains your server implementation.
 
@@ -134,6 +134,8 @@ The shopping list application's lambda handlers rely on the `@aws-sdk/client-dyn
 
 Then, let's copy the `handlers/src/dynamo-client.ts` file from the PDK project to `backend/src/operations` so it's available for our handlers.
 
+The `ts#smithy-api` generator scaffolds an example `Echo` operation. Since we removed this from our model, delete the corresponding handler in `backend/src/operations/echo.ts`. We'll register our migrated operations in `service.ts` further below.
+
 To migrate the handlers, you can follow these general steps:
 
 <Steps>
@@ -583,7 +585,7 @@ Additionally, update `packages/api/backend/project.json` and update `metadata.ap
     "generator": "ts#smithy-api",
 -    "apiName": "api",
 +    "apiName": "my-api",
-    "auth": "IAM",
+    "auth": "iam",
     "modelProject": "@shopping-list/api-model",
     "ports": [3001]
   },

diff --git a/docs/src/content/docs/en/snippets/pdk-migration/example/02-migrate-website.mdx b/docs/src/content/docs/en/snippets/pdk-migration/example/02-migrate-website.mdx
@@ -11,21 +11,21 @@ import InstallCommand from '@components/install-command.astro';
 
 The `CloudscapeReactTsWebsiteProject` used in the shopping list application configured a React website with CloudScape and Cognito authentication built in.
 
-This project type leveraged [`create-react-app`](https://github.com/facebook/create-react-app), which is now deprecated. For migrating the website in this guide, we will use the <Link path="/guides/react-website">`ts#react-website` generator</Link>, which uses more modern and supported technologies, namely [Vite](https://vite.dev/).
+This project type leveraged [`create-react-app`](https://github.com/facebook/create-react-app), which is now deprecated. For migrating the website in this guide, we will use the <Link path="/guides/react-website">`ts#website` generator</Link>, which uses more modern and supported technologies, namely [Vite](https://vite.dev/).
 
 As part of the migration, we will also move from PDK's configured React Router to [TanStack Router](https://tanstack.com/router), which adds additional type-safety to website routing.
 
 #### Generate a React Website
 
-Run the <Link path="/guides/react-website">`ts#react-website` generator</Link> to set up your website project in `packages/website`:
+Run the <Link path="/guides/react-website">`ts#website` generator</Link> with `framework` set to `react` to set up your website project in `packages/website`:
 
-<RunGenerator generator="ts#react-website" noInteractive requiredParameters={{ name: 'website' }} />
+<RunGenerator generator="ts#website" noInteractive requiredParameters={{ name: 'website', framework: 'react' }} />
 
 #### Add Cognito Authentication
 
-The React website generator above doesn't bundle cognito authentication by default like `CloudscapeReactTsWebsiteProject`, instead it's added explicitly via the <Link path="/guides/react-website-auth">`ts#react-website#auth` generator</Link>.
+The React website generator above doesn't bundle cognito authentication by default like `CloudscapeReactTsWebsiteProject`, instead it's added explicitly via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>.
 
-<RunGenerator generator="ts#react-website#auth" noInteractive requiredParameters={{ project: 'website', cognitoDomain: 'shopping-list' }} />
+<RunGenerator generator="ts#website#auth" noInteractive requiredParameters={{ project: 'website', cognitoDomain: 'shopping-list' }} />
 
 This adds React components which manage the appropriate redirects to ensure users log in using the Cognito hosted UI. This also adds a CDK construct to deploy the Cognito resources in `packages/common/constructs`, called `UserIdentity`.
 
@@ -61,6 +61,23 @@ The `CloudscapeReactTsWebsiteProject` automatically included a dependency on `@a
 
 <InstallCommand pkg="@aws-northstar/ui" />
 
+`@aws-northstar/ui` bundles a code editor component which depends on `ace-builds`, using a webpack-specific import that Vite cannot resolve. Since our shopping list application doesn't use this component, we exclude it from the bundle by adding it to the `external` configuration within the existing `build` options in `packages/website/vite.config.mts`:
+
+```diff lang="ts"
+// packages/website/vite.config.mts
+  build: {
+    outDir: '../../dist/packages/website',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
++    rollupOptions: {
++      external: ['ace-builds/webpack-resolver'],
++    },
+  },
+```
+
 #### Move the Components and Pages
 
 The [shopping list application](https://aws.github.io/aws-pdk/getting_started/shopping_list_app.html#create-new-pages-components) has one component called `CreateItem`, and two pages, `ShoppingList` and `ShoppingLists`. We'll migrate these to the new website, making a few adjustments since we're using TanStack Router and the Nx Plugin for AWS TypeScript client code generator.
@@ -79,7 +96,13 @@ Note that you'll now have some build errors visible in your IDE, we'll need to m
 
 #### Migrate from React Router to TanStack Router
 
-Since we're using [file-based routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), we can use the website local development server to manage automatically generating route configuration. Let's start the local website server:
+Since we're using [file-based routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), we can use the website local development server to manage automatically generating route configuration.
+
+The Smithy API's local server runs with [`tsx`](https://github.com/privatenumber/tsx), so let's add it as a development dependency before starting the local servers:
+
+<InstallCommand dev pkg="tsx" />
+
+Now let's start the local website server:
 
 <NxCommands commands={["serve-local website"]} />
 

diff --git a/docs/src/content/docs/en/snippets/pdk-migration/faq/type-safe-api.mdx b/docs/src/content/docs/en/snippets/pdk-migration/faq/type-safe-api.mdx
@@ -26,7 +26,7 @@ For Python, the [python-fastapi](https://openapi-generator.tech/docs/generators/
 
 ##### Client
 
-For TypeScript clients, you can use the <Link path="/guides/react-website">`ts#react-website` generator</Link> and <Link path="/guides/connection">`connection` generator</Link> with an example `ts#smithy-api` to see how clients are generated and integrated with a website. This configures build targets which generate clients by invoking our `open-api#ts-client` or `open-api#ts-hooks` generators. You can use these generators yourself by pointing them at your OpenAPI Specification.
+For TypeScript clients, you can use the <Link path="/guides/react-website">`ts#website` generator</Link> and <Link path="/guides/connection">`connection` generator</Link> with an example `ts#api` (with `framework` set to `smithy`) to see how clients are generated and integrated with a website. This configures build targets which generate clients by invoking our `open-api#ts-client` or `open-api#ts-hooks` generators. You can use these generators yourself by pointing them at your OpenAPI Specification.
 
 For other languages, you can also see if any of the generators from [OpenAPI Generator](https://openapi-generator.tech/docs/generators#client-generators) fit your needs.
 

diff --git a/docs/src/content/docs/es/snippets/pdk-migration/example/02-migrate-website.mdx b/docs/src/content/docs/es/snippets/pdk-migration/example/02-migrate-website.mdx
@@ -12,21 +12,21 @@ import InstallCommand from '@components/install-command.astro';
 
 El `CloudscapeReactTsWebsiteProject` utilizado en la aplicación de lista de compras configuró un sitio web React con CloudScape y autenticación Cognito integrada.
 
-Este tipo de proyecto utilizaba [`create-react-app`](https://github.com/facebook/create-react-app), que ahora está obsoleto. Para migrar el sitio web en esta guía, usaremos el <Link path="/guides/react-website">generador `ts#react-website`</Link>, que emplea tecnologías más modernas y soportadas, específicamente [Vite](https://vite.dev/).
+Este tipo de proyecto utilizaba [`create-react-app`](https://github.com/facebook/create-react-app), que ahora está obsoleto. Para migrar el sitio web en esta guía, usaremos el <Link path="/guides/react-website">generador `ts#website`</Link>, que emplea tecnologías más modernas y soportadas, específicamente [Vite](https://vite.dev/).
 
 Como parte de la migración, también cambiaremos del React Router configurado por PDK a [TanStack Router](https://tanstack.com/router), que añade mayor seguridad de tipos al enrutamiento del sitio web.
 
 #### Generar un sitio web React
 
-Ejecuta el <Link path="/guides/react-website">generador `ts#react-website`</Link> para configurar tu proyecto de sitio web en `packages/website`:
+Ejecuta el <Link path="/guides/react-website">generador `ts#website`</Link> con `framework` establecido en `react` para configurar tu proyecto de sitio web en `packages/website`:
 
-<RunGenerator generator="ts#react-website" noInteractive requiredParameters={{ name: 'website' }} />
+<RunGenerator generator="ts#website" noInteractive requiredParameters={{ name: 'website', framework: 'react' }} />
 
 #### Añadir autenticación Cognito
 
-El generador de sitios web React anterior no incluye autenticación Cognito por defecto como `CloudscapeReactTsWebsiteProject`, en su lugar se añade explícitamente mediante el <Link path="/guides/react-website-auth">generador `ts#react-website#auth`</Link>.
+El generador de sitios web React anterior no incluye autenticación Cognito por defecto como `CloudscapeReactTsWebsiteProject`, en su lugar se añade explícitamente mediante el <Link path="/guides/react-website-auth">generador `ts#website#auth`</Link>.
 
-<RunGenerator generator="ts#react-website#auth" noInteractive requiredParameters={{ project: 'website', cognitoDomain: 'shopping-list' }} />
+<RunGenerator generator="ts#website#auth" noInteractive requiredParameters={{ project: 'website', cognitoDomain: 'shopping-list' }} />
 
 Esto añade componentes React que gestionan las redirecciones necesarias para asegurar que los usuarios inicien sesión usando la interfaz alojada de Cognito. También añade un constructo CDK para desplegar los recursos de Cognito en `packages/common/constructs`, llamado `UserIdentity`.
 
@@ -62,6 +62,23 @@ El `CloudscapeReactTsWebsiteProject` incluía automáticamente una dependencia d
 
 <InstallCommand pkg="@aws-northstar/ui" />
 
+`@aws-northstar/ui` incluye un componente de editor de código que depende de `ace-builds`, usando una importación específica de webpack que Vite no puede resolver. Como nuestra aplicación de lista de compras no usa este componente, lo excluimos del bundle añadiéndolo a la configuración `external` dentro de las opciones `build` existentes en `packages/website/vite.config.mts`:
+
+```diff lang="ts"
+// packages/website/vite.config.mts
+  build: {
+    outDir: '../../dist/packages/website',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
++    rollupOptions: {
++      external: ['ace-builds/webpack-resolver'],
++    },
+  },
+```
+
 #### Mover componentes y páginas
 
 La [aplicación de lista de compras](https://aws.github.io/aws-pdk/getting_started/shopping_list_app.html#create-new-pages-components) tiene un componente llamado `CreateItem`, y dos páginas, `ShoppingList` y `ShoppingLists`. Migraremos estos elementos al nuevo sitio web, haciendo ajustes por el uso de TanStack Router y el generador de código cliente TypeScript del Plugin Nx para AWS.
@@ -80,7 +97,13 @@ Notarás algunos errores de compilación en tu IDE, necesitaremos hacer algunos
 
 #### Migrar de React Router a TanStack Router
 
-Al usar [enrutamiento basado en archivos](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), podemos usar el servidor de desarrollo local para generar automáticamente la configuración de rutas. Iniciemos el servidor local:
+Al usar [enrutamiento basado en archivos](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), podemos usar el servidor de desarrollo local del sitio web para gestionar la generación automática de la configuración de rutas.
+
+El servidor local de la API Smithy se ejecuta con [`tsx`](https://github.com/privatenumber/tsx), así que añadámoslo como dependencia de desarrollo antes de iniciar los servidores locales:
+
+<InstallCommand dev pkg="tsx" />
+
+Ahora iniciemos el servidor local del sitio web:
 
 <NxCommands commands={["serve-local website"]} />