swallowkit 0.4.0-beta.3 → 1.0.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/LICENSE +21 -21
  2. package/README.ja.md +254 -183
  3. package/README.md +311 -184
  4. package/dist/__tests__/fixtures.d.ts +14 -0
  5. package/dist/__tests__/fixtures.d.ts.map +1 -0
  6. package/dist/__tests__/fixtures.js +85 -0
  7. package/dist/__tests__/fixtures.js.map +1 -0
  8. package/dist/cli/commands/create-model.d.ts.map +1 -1
  9. package/dist/cli/commands/create-model.js +16 -15
  10. package/dist/cli/commands/create-model.js.map +1 -1
  11. package/dist/cli/commands/dev-seeds.d.ts +35 -0
  12. package/dist/cli/commands/dev-seeds.d.ts.map +1 -0
  13. package/dist/cli/commands/dev-seeds.js +292 -0
  14. package/dist/cli/commands/dev-seeds.js.map +1 -0
  15. package/dist/cli/commands/dev.d.ts +8 -0
  16. package/dist/cli/commands/dev.d.ts.map +1 -1
  17. package/dist/cli/commands/dev.js +308 -87
  18. package/dist/cli/commands/dev.js.map +1 -1
  19. package/dist/cli/commands/index.d.ts +1 -0
  20. package/dist/cli/commands/index.d.ts.map +1 -1
  21. package/dist/cli/commands/index.js +3 -1
  22. package/dist/cli/commands/index.js.map +1 -1
  23. package/dist/cli/commands/init.d.ts +13 -0
  24. package/dist/cli/commands/init.d.ts.map +1 -1
  25. package/dist/cli/commands/init.js +2639 -1708
  26. package/dist/cli/commands/init.js.map +1 -1
  27. package/dist/cli/commands/scaffold.d.ts +3 -0
  28. package/dist/cli/commands/scaffold.d.ts.map +1 -1
  29. package/dist/cli/commands/scaffold.js +283 -118
  30. package/dist/cli/commands/scaffold.js.map +1 -1
  31. package/dist/cli/index.js +17 -1
  32. package/dist/cli/index.js.map +1 -1
  33. package/dist/core/config.d.ts +2 -1
  34. package/dist/core/config.d.ts.map +1 -1
  35. package/dist/core/config.js +31 -1
  36. package/dist/core/config.js.map +1 -1
  37. package/dist/core/scaffold/functions-generator.d.ts +5 -0
  38. package/dist/core/scaffold/functions-generator.d.ts.map +1 -1
  39. package/dist/core/scaffold/functions-generator.js +649 -211
  40. package/dist/core/scaffold/functions-generator.js.map +1 -1
  41. package/dist/core/scaffold/model-parser.d.ts +1 -1
  42. package/dist/core/scaffold/model-parser.d.ts.map +1 -1
  43. package/dist/core/scaffold/model-parser.js +105 -101
  44. package/dist/core/scaffold/model-parser.js.map +1 -1
  45. package/dist/core/scaffold/nextjs-generator.js +181 -181
  46. package/dist/core/scaffold/openapi-generator.d.ts +3 -0
  47. package/dist/core/scaffold/openapi-generator.d.ts.map +1 -0
  48. package/dist/core/scaffold/openapi-generator.js +190 -0
  49. package/dist/core/scaffold/openapi-generator.js.map +1 -0
  50. package/dist/core/scaffold/ui-generator.js +656 -656
  51. package/dist/database/base-model.d.ts +3 -3
  52. package/dist/database/base-model.js +3 -3
  53. package/dist/index.d.ts +2 -2
  54. package/dist/index.d.ts.map +1 -1
  55. package/dist/index.js +2 -1
  56. package/dist/index.js.map +1 -1
  57. package/dist/types/index.d.ts +4 -0
  58. package/dist/types/index.d.ts.map +1 -1
  59. package/dist/utils/package-manager.d.ts +109 -0
  60. package/dist/utils/package-manager.d.ts.map +1 -0
  61. package/dist/utils/package-manager.js +215 -0
  62. package/dist/utils/package-manager.js.map +1 -0
  63. package/package.json +81 -73
  64. package/src/__tests__/__snapshots__/functions-generator.test.ts.snap +445 -0
  65. package/src/__tests__/__snapshots__/nextjs-generator.test.ts.snap +194 -0
  66. package/src/__tests__/__snapshots__/ui-generator.test.ts.snap +524 -0
  67. package/src/__tests__/config.test.ts +122 -0
  68. package/src/__tests__/dev-seeds.test.ts +112 -0
  69. package/src/__tests__/dev.test.ts +42 -0
  70. package/src/__tests__/fixtures.ts +83 -0
  71. package/src/__tests__/functions-generator.test.ts +101 -0
  72. package/src/__tests__/init.test.ts +80 -0
  73. package/src/__tests__/nextjs-generator.test.ts +97 -0
  74. package/src/__tests__/openapi-generator.test.ts +43 -0
  75. package/src/__tests__/package-manager.test.ts +189 -0
  76. package/src/__tests__/scaffold.test.ts +39 -0
  77. package/src/__tests__/string-utils.test.ts +75 -0
  78. package/src/__tests__/ui-generator.test.ts +144 -0
  79. package/src/cli/commands/create-model.ts +141 -0
  80. package/src/cli/commands/dev-seeds.ts +358 -0
  81. package/src/cli/commands/dev.ts +805 -0
  82. package/src/cli/commands/index.ts +9 -0
  83. package/src/cli/commands/init.ts +3370 -0
  84. package/src/cli/commands/provision.ts +193 -0
  85. package/src/cli/commands/scaffold.ts +786 -0
  86. package/src/cli/index.ts +74 -0
  87. package/src/core/config.ts +244 -0
  88. package/src/core/scaffold/functions-generator.ts +674 -0
  89. package/src/core/scaffold/model-parser.ts +627 -0
  90. package/src/core/scaffold/nextjs-generator.ts +217 -0
  91. package/src/core/scaffold/openapi-generator.ts +212 -0
  92. package/src/core/scaffold/ui-generator.ts +945 -0
  93. package/src/database/base-model.ts +184 -0
  94. package/src/database/client.ts +140 -0
  95. package/src/database/repository.ts +104 -0
  96. package/src/database/runtime-check.ts +25 -0
  97. package/src/index.ts +27 -0
  98. package/src/types/index.ts +45 -0
  99. package/src/utils/package-manager.ts +229 -0
  100. package/dist/cli/commands/build.d.ts +0 -6
  101. package/dist/cli/commands/build.d.ts.map +0 -1
  102. package/dist/cli/commands/build.js +0 -177
  103. package/dist/cli/commands/build.js.map +0 -1
  104. package/dist/cli/commands/deploy.d.ts +0 -3
  105. package/dist/cli/commands/deploy.d.ts.map +0 -1
  106. package/dist/cli/commands/deploy.js +0 -147
  107. package/dist/cli/commands/deploy.js.map +0 -1
  108. package/dist/cli/commands/setup.d.ts +0 -6
  109. package/dist/cli/commands/setup.d.ts.map +0 -1
  110. package/dist/cli/commands/setup.js +0 -254
  111. package/dist/cli/commands/setup.js.map +0 -1
package/README.md CHANGED
@@ -1,184 +1,311 @@
1
- # SwallowKit
2
-
3
- [![npm version](https://img.shields.io/npm/v/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
4
- [![npm downloads](https://img.shields.io/npm/dm/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
5
- [![license](https://img.shields.io/npm/l/swallowkit.svg)](./LICENSE)
6
-
7
- English | [日本語](./README.ja.md)
8
-
9
- **Type-safe schema-driven development toolkit for Next.js applications on Azure**
10
-
11
- SwallowKit enables developers to build full-stack Next.js applications with external Azure Functions backends while maintaining end-to-end type safety through shared Zod schemas.
12
-
13
- Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
14
-
15
- Next.js API routes are restricted to use only as BFF (Backend For Frontend), offloading business logic to Azure Functions to provide clear separation between client and server.
16
-
17
- Featuring Scaffold functionality to automatically generate CRUD operations from Zod schemas, achieving type-safe integration with Cosmos DB and consistent type definitions and validation.
18
-
19
- > **Note**: This project is in active development. APIs may change in future versions.
20
-
21
- ## ✨ Key Features
22
-
23
- - **🔄 Zod Schema Sharing** - Same schema across frontend, BFF, Azure Functions, and Cosmos DB
24
- - **⚡ CRUD Code Generation** - Auto-generate Azure Functions + Next.js code with `swallowkit scaffold`
25
- - **🛡️ Full Type Safety** - End-to-end TypeScript from client to database
26
- - **🎯 BFF Pattern** - Next.js API Routes as BFF layer with auto-validation and resource inference
27
- - **☁️ Azure Optimized** - Minimal-cost architecture with Static Web Apps + Functions + Cosmos DB
28
- - **🚀 Easy Deployment** - Auto-generated Bicep IaC + CI/CD workflows
29
-
30
- ## 📚 Documentation
31
-
32
- - **[CLI Reference](./docs/cli-reference.md)** - All commands in detail
33
- - **[Scaffold Guide](./docs/scaffold-guide.md)** - CRUD code generation
34
- - **[Zod Schema Sharing Guide](./docs/zod-schema-sharing-guide.md)** - Schema design
35
- - **[Deployment Guide](./docs/deployment-guide.md)** - Deploy to Azure
36
-
37
- ## 🚀 Quick Start
38
-
39
- ### 1. Create Project
40
-
41
- ```bash
42
- npx swallowkit init my-app
43
- cd my-app
44
- ```
45
-
46
- ### 2. Create Model
47
-
48
- ```bash
49
- npx swallowkit create-model todo
50
- ```
51
-
52
- This generates `lib/models/todo.ts`. Customize it by adding your required fields:
53
-
54
- ```typescript
55
- // lib/models/todo.ts
56
- import { z } from 'zod';
57
-
58
- export const todoSchema = z.object({
59
- id: z.string(),
60
- text: z.string().min(1).max(200),
61
- completed: z.boolean().default(false),
62
- createdAt: z.string().optional(),
63
- updatedAt: z.string().optional(),
64
- });
65
-
66
- export type Todo = z.infer<typeof todoSchema>;
67
- ```
68
-
69
- ### 3. Generate CRUD Code
70
-
71
- ```bash
72
- npx swallowkit scaffold lib/models/todo.ts
73
- ```
74
-
75
- This auto-generates:
76
- - Azure Functions (CRUD endpoints + Cosmos DB bindings)
77
- - ✅ Next.js BFF API Routes (auto-validation + resource inference)
78
- - React Components (type-safe forms)
79
-
80
- ### 4. Start Development Server
81
-
82
- ```bash
83
- npx swallowkit dev
84
- ```
85
-
86
- - Next.js: http://localhost:3000
87
- - Azure Functions: http://localhost:7071
88
-
89
- ### 5. Use from Frontend
90
-
91
- ```typescript
92
- import { api } from '@/lib/api/backend';
93
- import type { Todo } from '@/lib/models/todo';
94
-
95
- // Get all - call BFF endpoint
96
- const todos = await api.get<Todo[]>('/api/todos');
97
-
98
- // Create - validated by backend
99
- const created = await api.post<Todo>('/api/todos', {
100
- text: 'Buy milk',
101
- completed: false
102
- });
103
-
104
- // Update - validated by backend
105
- const updated = await api.put<Todo>('/api/todos/123', { completed: true });
106
-
107
- // Delete
108
- await api.delete('/api/todos/123');
109
- ```
110
-
111
- ## 🏗️ Architecture
112
-
113
- ```
114
- ┌─────────────────────────────────────────────────────────────┐
115
- │ Frontend (React) │
116
- │ - Client Components │
117
- │ - Server Components (SSR) │
118
- └──────────────────────────┬───────────────────────────────────┘
119
- │ api.post('/api/todos', data)
120
-
121
- ┌─────────────────────────────────────────────────────────────┐
122
- │ BFF Layer (Next.js API Routes) │
123
- │ - Auto Schema Validation (Zod) │
124
- │ - Error Handling │
125
- └──────────────────────────┬───────────────────────────────────┘
126
- HTTP Request
127
-
128
- ┌─────────────────────────────────────────────────────────────┐
129
- │ Azure Functions (Backend)
130
- │ - HTTP Triggers (CRUD) │
131
- │ - Zod Validation (Re-check) │
132
- │ - Business Logic │
133
- │ - Cosmos DB Bindings │
134
- └──────────────────────────┬───────────────────────────────────┘
135
-
136
-
137
- ┌─────────────────────────────────────────────────────────────┐
138
- │ Azure Cosmos DB │
139
- │ - NoSQL Database │
140
- │ - Zod Schema Validation │
141
- └─────────────────────────────────────────────────────────────┘
142
- ```
143
-
144
- **Key Patterns:**
145
- - **BFF (Backend For Frontend)**: Next.js API Routes proxy to Azure Functions
146
- - **Shared Schemas**: Zod schemas used across frontend, BFF, Functions, and DB
147
- - **Type Safety**: TypeScript types auto-inferred from Zod
148
- - **Managed Identity**: Secure service connections (no connection strings)
149
-
150
- ## 📦 Prerequisites
151
-
152
- - Node.js 22.x
153
- - Azure Cosmos DB Emulator (local development)
154
- - [Official documentation (vNext recommended)](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux)
155
- - Windows: [Download](https://aka.ms/cosmosdb-emulator)
156
- - Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
157
-
158
- ## 🚀 Deploy to Azure
159
-
160
- Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
161
-
162
- ```bash
163
- # 1. Provision resources (Bicep IaC)
164
- npx swallowkit provision --resource-group my-app-rg --location japaneast
165
-
166
- # 2. Configure CI/CD secrets (see deployment guide for details)
167
-
168
- # 3. Push code for auto-deploy
169
- git push origin main
170
- ```
171
-
172
- See **[Deployment Guide](./docs/deployment-guide.md)** for details.
173
-
174
- ## License
175
-
176
- MIT
177
-
178
- ## 🔗 Related Links
179
-
180
- - [Azure Static Web Apps](https://learn.microsoft.com/en-us/azure/static-web-apps/)
181
- - [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/)
182
- - [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
183
- - [Next.js](https://nextjs.org/)
184
- - [Zod](https://zod.dev/)
1
+ # SwallowKit
2
+
3
+ [![npm version](https://img.shields.io/npm/v/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
4
+ [![npm downloads](https://img.shields.io/npm/dm/swallowkit.svg)](https://www.npmjs.com/package/swallowkit)
5
+ [![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/himanago.swallowkit-vscode?label=VS%20Code%20Extension)](https://marketplace.visualstudio.com/items?itemName=himanago.swallowkit-vscode)
6
+ [![license](https://img.shields.io/npm/l/swallowkit.svg)](./LICENSE)
7
+
8
+ English | [日本語](./README.ja.md)
9
+
10
+ **Type-safe schema-driven development toolkit for Next.js applications on Azure**
11
+
12
+ SwallowKit enables developers to build full-stack Next.js applications with external Azure Functions backends while maintaining end-to-end type safety through shared Zod schemas.
13
+
14
+ Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
15
+
16
+ Next.js API routes are restricted to use only as BFF (Backend For Frontend), offloading business logic to Azure Functions to provide clear separation between client and server.
17
+
18
+ Featuring Scaffold functionality to automatically generate CRUD operations from Zod schemas, achieving type-safe integration with Cosmos DB and consistent type definitions and validation.
19
+
20
+ > **Note**: This project is in active development. APIs may change in future versions.
21
+
22
+ ## ✨ Key Features
23
+
24
+ - **🔄 Zod Schema Sharing** - Keep Zod as the source of truth across frontend, BFF, Azure Functions, and Cosmos DB
25
+ - **⚡ CRUD Code Generation** - Auto-generate Azure Functions + Next.js code with `swallowkit scaffold`
26
+ - **🌐 Multi-language Functions Backends** - Choose TypeScript, C#, or Python for Azure Functions during `init`
27
+ - **🧬 OpenAPI Schema Bridge** - For C#/Python backends, `scaffold` exports OpenAPI from Zod and generates backend schema assets
28
+ - **🛡️ Contract Safety** - Keep frontend/BFF contracts aligned with backend implementations through shared Zod or generated OpenAPI-derived models
29
+ - **🎯 BFF Pattern** - Next.js API Routes as BFF layer with auto-validation and resource inference
30
+ - **☁️ Azure Optimized** - Minimal-cost architecture with Static Web Apps + Functions + Cosmos DB
31
+ - **🚀 Easy Deployment** - Auto-generated Bicep IaC + CI/CD workflows
32
+ - **🤖 AI-Friendly** - Auto-generated instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`) and layer-specific rules help GitHub Copilot, Claude Code, and OpenAI Codex follow project conventions
33
+ - **🧩 [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=himanago.swallowkit-vscode)** - GUI wizard for init/scaffold/dev, right-click model scaffolding, dev server status bar, and TypeScript snippets
34
+
35
+ ## 📚 Documentation
36
+
37
+ Visit the **[SwallowKit Documentation](https://himanago.github.io/swallowkit/)** for the full docs (also available in [日本語](https://himanago.github.io/swallowkit/ja/)).
38
+
39
+ - **[CLI Reference](https://himanago.github.io/swallowkit/en/cli-reference)** - All commands in detail
40
+ - **[Scaffold Guide](https://himanago.github.io/swallowkit/en/scaffold-guide)** - CRUD code generation
41
+ - **[Zod Schema Sharing Guide](https://himanago.github.io/swallowkit/en/zod-schema-sharing-guide)** - Schema design
42
+ - **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** - Deploy to Azure
43
+
44
+ ## 🚀 Quick Start
45
+
46
+ ### 1. Create Project
47
+
48
+ ```bash
49
+ npx swallowkit init my-app
50
+ # or
51
+ pnpm dlx swallowkit init my-app
52
+ cd my-app
53
+ ```
54
+
55
+ The interactive prompts ask for CI/CD provider, Azure Functions backend language, Cosmos DB mode, and network settings. You can also specify them as flags to skip prompts entirely:
56
+
57
+ ```bash
58
+ # Non-interactive mode (useful for VS Code extensions or automation)
59
+ npx swallowkit init my-app --cicd github --backend-language python --cosmos-db-mode serverless --vnet outbound
60
+ ```
61
+
62
+ | Flag | Values | Description |
63
+ |------|--------|-------------|
64
+ | `--cicd <provider>` | `github`, `azure`, `skip` | CI/CD provider |
65
+ | `--backend-language <language>` | `typescript`, `csharp`, `python` | Azure Functions backend language |
66
+ | `--cosmos-db-mode <mode>` | `freetier`, `serverless` | Cosmos DB pricing mode |
67
+ | `--vnet <option>` | `outbound`, `none` | Network security |
68
+
69
+ Omit any flag to be prompted for that value interactively.
70
+
71
+ ### 2. Create Models
72
+
73
+ You can create multiple models at once:
74
+
75
+ ```bash
76
+ npx swallowkit create-model category todo
77
+ # or
78
+ pnpm dlx swallowkit create-model category todo
79
+ ```
80
+
81
+ This generates `shared/models/category.ts` and `shared/models/todo.ts`. Customize them by adding your required fields:
82
+
83
+ ```typescript
84
+ // shared/models/category.ts
85
+ import { z } from 'zod';
86
+
87
+ export const category = z.object({
88
+ id: z.string(),
89
+ name: z.string().min(1).max(50),
90
+ createdAt: z.string().optional(),
91
+ updatedAt: z.string().optional(),
92
+ });
93
+
94
+ export type Category = z.infer<typeof category>;
95
+ ```
96
+
97
+ For parent-child relationships, use **nested schemas** instead of ID references:
98
+
99
+ ```typescript
100
+ // shared/models/todo.ts
101
+ import { z } from 'zod';
102
+ import { category } from './category';
103
+
104
+ export const todo = z.object({
105
+ id: z.string(),
106
+ text: z.string().min(1).max(200),
107
+ completed: z.boolean().default(false),
108
+ category: category.optional(), // Nested object (not categoryId)
109
+ createdAt: z.string().optional(),
110
+ updatedAt: z.string().optional(),
111
+ });
112
+
113
+ export type Todo = z.infer<typeof todo>;
114
+ ```
115
+
116
+ > **Tip**: Nesting preserves type safety and stores related data together in the document, which is natural for Cosmos DB's document model.
117
+
118
+ ### 3. Generate CRUD Code
119
+
120
+ ```bash
121
+ npx swallowkit scaffold shared/models/todo.ts
122
+ # or
123
+ pnpm dlx swallowkit scaffold shared/models/todo.ts
124
+ ```
125
+
126
+ This auto-generates:
127
+ - ✅ Azure Functions (CRUD endpoints + Cosmos DB bindings)
128
+ - ✅ Next.js BFF API Routes (auto-validation + resource inference)
129
+ - React Components (type-safe forms)
130
+
131
+ If you selected `csharp` or `python` at `init` time, `swallowkit scaffold` also writes an OpenAPI document under `functions/openapi/` and generates backend schema assets under `functions/generated/`.
132
+
133
+ ### 4. Start Development Server
134
+
135
+ ```bash
136
+ npx swallowkit dev
137
+ # or
138
+ pnpm dlx swallowkit dev
139
+ ```
140
+
141
+ - Next.js: http://localhost:3000
142
+ - Azure Functions: http://localhost:7071
143
+
144
+ If you want to replace Cosmos DB Emulator data before startup, generate an environment template and then launch `dev` with that environment:
145
+
146
+ ```bash
147
+ npx swallowkit create-dev-seeds local
148
+ # edit dev-seeds/local/*.json
149
+ npx swallowkit dev --seed-env local
150
+ ```
151
+
152
+ This workflow is designed for local debugging against the Cosmos DB Emulator:
153
+
154
+ - `create-dev-seeds <environment>` generates one JSON template per schema under `dev-seeds/<environment>/`
155
+ - each file name maps to a schema/container, for example `shared/models/todo.ts` -> `dev-seeds/local/todo.json` -> `Todos`
156
+ - when you start `dev --seed-env <environment>`, SwallowKit replaces the existing data for each matching container with the JSON documents from that environment
157
+ - containers without a matching JSON file are left untouched
158
+ - if `--seed-env` is omitted, or `dev-seeds/<environment>/` does not exist, current emulator data is preserved
159
+
160
+ Example file layout:
161
+
162
+ ```text
163
+ dev-seeds/
164
+ local/
165
+ todo.json
166
+ category.json
167
+ staging-debug/
168
+ todo.json
169
+ ```
170
+
171
+ Each `{schema}.json` file can contain either a single JSON object or an array of JSON objects. Every document must include an `id`:
172
+
173
+ ```json
174
+ [
175
+ {
176
+ "id": "seed-todo-001",
177
+ "name": "Seed todo one",
178
+ "createdAt": "2026-03-21T00:00:00.000Z",
179
+ "updatedAt": "2026-03-21T00:00:00.000Z"
180
+ },
181
+ {
182
+ "id": "seed-todo-002",
183
+ "name": "Seed todo two",
184
+ "createdAt": "2026-03-21T00:00:01.000Z",
185
+ "updatedAt": "2026-03-21T00:00:01.000Z"
186
+ }
187
+ ]
188
+ ```
189
+
190
+ Recommended workflow:
191
+
192
+ ```bash
193
+ npx swallowkit create-model todo
194
+ npx swallowkit scaffold shared/models/todo.ts
195
+ npx swallowkit create-dev-seeds local
196
+ # edit dev-seeds/local/todo.json
197
+ npx swallowkit dev --seed-env local
198
+ ```
199
+
200
+ ### 5. Use from Frontend
201
+
202
+ ```typescript
203
+ import { api } from '@/lib/api/backend';
204
+ import type { Todo } from '@/shared/models/todo';
205
+
206
+ // Get all - call BFF endpoint
207
+ const todos = await api.get<Todo[]>('/api/todos');
208
+
209
+ // Create - validated by backend
210
+ const created = await api.post<Todo>('/api/todos', {
211
+ text: 'Buy milk',
212
+ completed: false
213
+ });
214
+
215
+ // Update - validated by backend
216
+ const updated = await api.put<Todo>('/api/todos/123', { completed: true });
217
+
218
+ // Delete
219
+ await api.delete('/api/todos/123');
220
+ ```
221
+
222
+ ## 🏗️ Architecture
223
+
224
+ ```
225
+ ┌─────────────────────────────────────────────────────────────┐
226
+ │ Frontend (React) │
227
+ │ - Client Components │
228
+ │ - Server Components (SSR) │
229
+ └──────────────────────────┬───────────────────────────────────┘
230
+ │ api.post('/api/todos', data)
231
+
232
+ ┌─────────────────────────────────────────────────────────────┐
233
+ │ BFF Layer (Next.js API Routes) │
234
+ │ - Auto Schema Validation (Zod) │
235
+ │ - Error Handling │
236
+ └──────────────────────────┬───────────────────────────────────┘
237
+ │ HTTP Request
238
+
239
+ ┌─────────────────────────────────────────────────────────────┐
240
+ │ Azure Functions (Backend) │
241
+ │ - HTTP Triggers (CRUD) │
242
+ │ - Zod Validation (Re-check) │
243
+ │ - Business Logic │
244
+ │ - Cosmos DB Bindings │
245
+ └──────────────────────────┬───────────────────────────────────┘
246
+
247
+
248
+ ┌─────────────────────────────────────────────────────────────┐
249
+ │ Azure Cosmos DB │
250
+ │ - NoSQL Database │
251
+ │ - Zod Schema Validation │
252
+ └─────────────────────────────────────────────────────────────┘
253
+ ```
254
+
255
+ **Key Patterns:**
256
+ - **BFF (Backend For Frontend)**: Next.js API Routes proxy to Azure Functions
257
+ - **Shared Schemas**: Zod schemas stay in `shared/models/` as the source of truth
258
+ - **OpenAPI Bridge for C#/Python**: Non-TypeScript Functions consume generated assets under `functions/generated/`
259
+ - **Contract Safety**: BFF and backend stay aligned through shared Zod or generated backend models
260
+ - **Managed Identity**: Secure service connections (no connection strings)
261
+
262
+ ## 📦 Prerequisites
263
+
264
+ - Node.js 22.x
265
+ - **pnpm** (recommended): `corepack enable` or `npm install -g pnpm`
266
+ - npm also works — SwallowKit auto-detects the package manager (if pnpm is installed, it is always preferred)
267
+ - Azure Cosmos DB Emulator (local development)
268
+ - [Official documentation (vNext recommended)](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux)
269
+ - Windows: [Download](https://aka.ms/cosmosdb-emulator)
270
+ - Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
271
+
272
+ ## 🚀 Deploy to Azure
273
+
274
+ Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
275
+
276
+ **1. Provision resources (Bicep IaC)**
277
+
278
+ ```bash
279
+ npx swallowkit provision --resource-group my-app-rg --location japaneast
280
+ # or
281
+ pnpm dlx swallowkit provision --resource-group my-app-rg --location japaneast
282
+ ```
283
+
284
+ After provisioning, the required CI/CD secret values are displayed in the terminal. Copy them.
285
+
286
+ **2. Push code**
287
+
288
+ ```bash
289
+ git push origin main
290
+ ```
291
+
292
+ **3. Cancel the auto-triggered CI/CD run** — it will fail because secrets are not registered yet.
293
+
294
+ **4. Register the displayed secret values** in GitHub (Settings → Secrets) or Azure DevOps (Pipelines → Library).
295
+
296
+ **5. Manually re-run the CI/CD workflow.**
297
+
298
+ See **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** for details.
299
+
300
+ ## License
301
+
302
+ MIT
303
+
304
+ ## 🔗 Related Links
305
+
306
+ - [SwallowKit VS Code Extension](https://marketplace.visualstudio.com/items?itemName=himanago.swallowkit-vscode)
307
+ - [Azure Static Web Apps](https://learn.microsoft.com/en-us/azure/static-web-apps/)
308
+ - [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/)
309
+ - [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
310
+ - [Next.js](https://nextjs.org/)
311
+ - [Zod](https://zod.dev/)
@@ -0,0 +1,14 @@
1
+ import { ModelInfo } from "../core/scaffold/model-parser";
2
+ /**
3
+ * テスト用の基本的な ModelInfo フィクスチャ
4
+ */
5
+ export declare function createBasicModelInfo(overrides?: Partial<ModelInfo>): ModelInfo;
6
+ /**
7
+ * 外部キーを含む ModelInfo フィクスチャ
8
+ */
9
+ export declare function createModelInfoWithForeignKey(): ModelInfo;
10
+ /**
11
+ * enum フィールドを含む ModelInfo フィクスチャ
12
+ */
13
+ export declare function createModelInfoWithEnum(): ModelInfo;
14
+ //# sourceMappingURL=fixtures.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/__tests__/fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAoB9E;AAED;;GAEG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,CAqBzD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,SAAS,CA0BnD"}
@@ -0,0 +1,85 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.createBasicModelInfo = createBasicModelInfo;
4
+ exports.createModelInfoWithForeignKey = createModelInfoWithForeignKey;
5
+ exports.createModelInfoWithEnum = createModelInfoWithEnum;
6
+ /**
7
+ * テスト用の基本的な ModelInfo フィクスチャ
8
+ */
9
+ function createBasicModelInfo(overrides) {
10
+ return {
11
+ name: "Todo",
12
+ displayName: "Todo",
13
+ schemaName: "todoSchema",
14
+ filePath: "/models/todo.ts",
15
+ fields: [
16
+ { name: "id", type: "string", isOptional: false, isArray: false },
17
+ { name: "title", type: "string", isOptional: false, isArray: false },
18
+ { name: "description", type: "string", isOptional: true, isArray: false },
19
+ { name: "completed", type: "boolean", isOptional: false, isArray: false },
20
+ { name: "createdAt", type: "string", isOptional: false, isArray: false },
21
+ { name: "updatedAt", type: "string", isOptional: false, isArray: false },
22
+ ],
23
+ hasId: true,
24
+ hasCreatedAt: true,
25
+ hasUpdatedAt: true,
26
+ nestedSchemaRefs: [],
27
+ ...overrides,
28
+ };
29
+ }
30
+ /**
31
+ * 外部キーを含む ModelInfo フィクスチャ
32
+ */
33
+ function createModelInfoWithForeignKey() {
34
+ return createBasicModelInfo({
35
+ name: "Task",
36
+ displayName: "Task",
37
+ schemaName: "taskSchema",
38
+ filePath: "/models/task.ts",
39
+ fields: [
40
+ { name: "id", type: "string", isOptional: false, isArray: false },
41
+ { name: "title", type: "string", isOptional: false, isArray: false },
42
+ {
43
+ name: "categoryId",
44
+ type: "string",
45
+ isOptional: false,
46
+ isArray: false,
47
+ isForeignKey: true,
48
+ referencedModel: "Category",
49
+ },
50
+ { name: "createdAt", type: "string", isOptional: false, isArray: false },
51
+ { name: "updatedAt", type: "string", isOptional: false, isArray: false },
52
+ ],
53
+ });
54
+ }
55
+ /**
56
+ * enum フィールドを含む ModelInfo フィクスチャ
57
+ */
58
+ function createModelInfoWithEnum() {
59
+ return createBasicModelInfo({
60
+ name: "Issue",
61
+ displayName: "Issue",
62
+ schemaName: "issueSchema",
63
+ filePath: "/models/issue.ts",
64
+ fields: [
65
+ { name: "id", type: "string", isOptional: false, isArray: false },
66
+ { name: "title", type: "string", isOptional: false, isArray: false },
67
+ {
68
+ name: "status",
69
+ type: "string",
70
+ isOptional: false,
71
+ isArray: false,
72
+ enumValues: ["open", "in_progress", "closed"],
73
+ },
74
+ {
75
+ name: "priority",
76
+ type: "number",
77
+ isOptional: true,
78
+ isArray: false,
79
+ },
80
+ { name: "createdAt", type: "string", isOptional: false, isArray: false },
81
+ { name: "updatedAt", type: "string", isOptional: false, isArray: false },
82
+ ],
83
+ });
84
+ }
85
+ //# sourceMappingURL=fixtures.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../src/__tests__/fixtures.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"create-model.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/create-model.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,UAAU,kBAAkB;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0CD;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,iBA2DnE"}
1
+ {"version":3,"file":"create-model.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/create-model.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,UAAU,kBAAkB;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0CD;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,iBA2DnE"}