fix(create-voltagent-app): align template module resolution with Node… (#587)

* fix(create-voltagent-app): align template module resolution with NodeNext

* fix(create-voltagent-app): bundle template apps with tsdown

* docs(quick-start): document tsdown bundling workflow

Author: wayneg123

.changeset/node-esm-template-fix.md

@@ -0,0 +1,5 @@
+---
+"create-voltagent-app": patch
+---
+
+Switch the app template to bundle with tsdown so the production build runs under Node ESM without manual .js extensions or bespoke import mappers.

packages/create-voltagent-app/src/utils/dependency-installer.ts

@@ -28,7 +28,7 @@ export const createBaseDependencyInstaller = async (
     type: "module",
     scripts: {
       dev: "tsx watch --env-file=.env ./src",
-      build: "tsc",
+      build: "tsdown",
       start: "node dist/index.js",
       lint: "biome check ./src",
       "lint:fix": "biome check --write ./src",
@@ -48,11 +48,12 @@ export const createBaseDependencyInstaller = async (
     devDependencies: {
       "@biomejs/biome": "^1.9.4",
       "@types/node": "^22.10.5",
+      tsdown: "^0.15.2",
       tsx: "^4.19.2",
       typescript: "^5.7.3",
     },
     engines: {
-      node: ">=20.0.0",
+      node: ">=20.19.0",
     },
   };
 

packages/create-voltagent-app/src/utils/templates.ts

@@ -11,6 +11,10 @@ export const getBaseTemplates = (): TemplateFile[] => {
       sourcePath: path.join(TEMPLATES_DIR, "base/tsconfig.json.template"),
       targetPath: "tsconfig.json",
     },
+    {
+      sourcePath: path.join(TEMPLATES_DIR, "base/tsdown.config.ts.template"),
+      targetPath: "tsdown.config.ts",
+    },
     {
       sourcePath: path.join(TEMPLATES_DIR, "base/README.md.template"),
       targetPath: "README.md",

packages/create-voltagent-app/templates/base/tools/index.ts.template

@@ -1,2 +1,2 @@
 // Export all tools from this directory
-export { weatherTool } from "./weather";
+export { weatherTool } from "./weather";

packages/create-voltagent-app/templates/base/tsconfig.json.template

@@ -11,4 +11,4 @@
   },
   "include": ["src"],
   "exclude": ["node_modules", "dist"]
-} 
+} 

packages/create-voltagent-app/templates/base/tsdown.config.ts.template

@@ -0,0 +1,7 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["./src/index.ts"],
+  sourcemap: true,
+  outDir: "dist",
+});

website/docs/getting-started/quick-start.md

@@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem';
 
 # Quick Start
 
-There are two ways to create a VoltAgent application: Automatic setup or manual setup. While both work, the automatic setup provides the smoothest experience, especially for new users.
+There are two ways to create a VoltAgent application: Automatic setup or manual setup. While both work, the automatic setup provides the smoothest experience, especially for new users. Be sure your environment is running **Node.js 20.19 or newer** so the generated tsdown build works without ESM resolution issues.
 
 ### Automatic Setup (Recommended)
 
@@ -72,10 +72,12 @@ The CLI will guide you through the setup process:
 
 The tool will automatically:
 
-- Create project files and structure
+- Create project files and structure (including a `tsdown.config.ts` build configuration)
 - Generate a `.env` file with your API key (if provided)
 - Initialize a git repository
-- Install dependencies Once the setup is complete, navigate to your project directory:
+- Install dependencies
+
+Once the setup is complete, navigate to your project directory:
 
 ```bash
 cd my-voltagent-app
@@ -167,6 +169,39 @@ You should receive a response from your AI agent in the chat window. This confir
 
 The `dev` script uses `tsx watch`, so it will automatically restart if you make changes to your code in the `src` directory. Press `Ctrl+C` in the terminal to stop the agent.
 
+### Build for Production
+
+When you're ready to deploy, bundle the app and run the compiled JavaScript with Node:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+
+```bash
+npm run build
+npm start
+```
+
+  </TabItem>
+  <TabItem value="yarn" label="yarn">
+
+```bash
+yarn build
+yarn start
+```
+
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm build
+pnpm start
+```
+
+  </TabItem>
+</Tabs>
+
+The `build` script invokes **tsdown**, which bundles your TypeScript entrypoint (and any sibling directories such as `./workflows` or `./tools`) into `dist/index.js`. This extra step keeps the Node ESM loader from throwing `ERR_UNSUPPORTED_DIR_IMPORT` while preserving extensionless imports during development.
+
 ### Explore and Run Your Workflow from the Console
 
 Your new project isn't just an agent; it's a powerful automation engine. We've included an expense approval workflow example to get you started, and you can run it directly from the VoltOps console.
@@ -256,14 +291,26 @@ Create a basic TypeScript configuration file (tsconfig.json):
 }
 ```
 
+Add a `tsdown.config.ts` alongside `tsconfig.json` so production builds bundle correctly:
+
+```typescript
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["./src/index.ts"],
+  sourcemap: true,
+  outDir: "dist",
+});
+```
+
 #### Install Dependencies
 
 <Tabs>
   <TabItem value="npm" label="npm" default>
 
 ```bash
 # Install development dependencies
-npm install --save-dev typescript tsx @types/node @voltagent/cli
+npm install --save-dev typescript tsx tsdown @types/node @voltagent/cli
 
 # Install dependencies
 npm install @voltagent/core @voltagent/libsql @voltagent/server-hono @voltagent/logger ai @ai-sdk/openai@^2 zod@3
@@ -274,7 +321,7 @@ npm install @voltagent/core @voltagent/libsql @voltagent/server-hono @voltagent/
 
 ```bash
 # Install development dependencies
-yarn add --dev typescript tsx @types/node @voltagent/cli
+yarn add --dev typescript tsx tsdown @types/node @voltagent/cli
 
 # Install dependencies
 yarn add @voltagent/core @voltagent/libsql @voltagent/server-hono @voltagent/logger ai @ai-sdk/openai@^2 zod@3
@@ -285,7 +332,7 @@ yarn add @voltagent/core @voltagent/libsql @voltagent/server-hono @voltagent/log
 
 ```bash
 # Install development dependencies
-pnpm add --save-dev typescript tsx @types/node @voltagent/cli
+pnpm add --save-dev typescript tsx tsdown @types/node @voltagent/cli
 
 # Install dependencies
 pnpm add @voltagent/core @voltagent/libsql @voltagent/server-hono @voltagent/logger ai @ai-sdk/openai@^2 zod@3
@@ -349,13 +396,15 @@ Add the following to your package.json:
 ```json
 "type": "module",
 "scripts": {
-  "build": "tsc",
+  "build": "tsdown",
   "dev": "tsx watch --env-file=.env ./src",
   "start": "node dist/index.js",
   "volt": "volt" // Requires @voltagent/cli
 }
 ```
 
+`npm run build` (or `yarn build` / `pnpm build`) bundles your sources with tsdown before handing the output to Node via `npm start`.
+
 Your project structure should now look like this:
 
 ```
@@ -365,6 +414,7 @@ my-voltagent-project/
 │   └── index.ts
 ├── package.json
 ├── tsconfig.json
+├── tsdown.config.ts
 ├── .env
 └── .voltagent/ (created automatically when you run the agent)
 ```