swallowkit 1.0.0-beta.5 → 1.0.0-beta.7

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 (97) hide show
  1. package/LICENSE +21 -21
  2. package/README.ja.md +251 -242
  3. package/README.md +252 -243
  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.js +14 -14
  9. package/dist/cli/commands/dev.d.ts +8 -0
  10. package/dist/cli/commands/dev.d.ts.map +1 -1
  11. package/dist/cli/commands/dev.js +238 -30
  12. package/dist/cli/commands/dev.js.map +1 -1
  13. package/dist/cli/commands/init.d.ts +5 -0
  14. package/dist/cli/commands/init.d.ts.map +1 -1
  15. package/dist/cli/commands/init.js +2507 -1664
  16. package/dist/cli/commands/init.js.map +1 -1
  17. package/dist/cli/commands/scaffold.d.ts +3 -0
  18. package/dist/cli/commands/scaffold.d.ts.map +1 -1
  19. package/dist/cli/commands/scaffold.js +281 -117
  20. package/dist/cli/commands/scaffold.js.map +1 -1
  21. package/dist/cli/index.js +2 -0
  22. package/dist/cli/index.js.map +1 -1
  23. package/dist/core/config.d.ts +2 -1
  24. package/dist/core/config.d.ts.map +1 -1
  25. package/dist/core/config.js +28 -0
  26. package/dist/core/config.js.map +1 -1
  27. package/dist/core/scaffold/functions-generator.d.ts +5 -0
  28. package/dist/core/scaffold/functions-generator.d.ts.map +1 -1
  29. package/dist/core/scaffold/functions-generator.js +649 -218
  30. package/dist/core/scaffold/functions-generator.js.map +1 -1
  31. package/dist/core/scaffold/model-parser.d.ts +1 -1
  32. package/dist/core/scaffold/model-parser.js +99 -99
  33. package/dist/core/scaffold/nextjs-generator.js +181 -181
  34. package/dist/core/scaffold/openapi-generator.d.ts +3 -0
  35. package/dist/core/scaffold/openapi-generator.d.ts.map +1 -0
  36. package/dist/core/scaffold/openapi-generator.js +190 -0
  37. package/dist/core/scaffold/openapi-generator.js.map +1 -0
  38. package/dist/core/scaffold/ui-generator.js +656 -656
  39. package/dist/database/base-model.d.ts +3 -3
  40. package/dist/database/base-model.js +3 -3
  41. package/dist/index.d.ts +2 -2
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js +2 -1
  44. package/dist/index.js.map +1 -1
  45. package/dist/types/index.d.ts +4 -0
  46. package/dist/types/index.d.ts.map +1 -1
  47. package/dist/utils/package-manager.d.ts +2 -1
  48. package/dist/utils/package-manager.d.ts.map +1 -1
  49. package/dist/utils/package-manager.js +14 -10
  50. package/dist/utils/package-manager.js.map +1 -1
  51. package/package.json +81 -74
  52. package/src/__tests__/__snapshots__/functions-generator.test.ts.snap +445 -0
  53. package/src/__tests__/__snapshots__/nextjs-generator.test.ts.snap +194 -0
  54. package/src/__tests__/__snapshots__/ui-generator.test.ts.snap +524 -0
  55. package/src/__tests__/config.test.ts +122 -0
  56. package/src/__tests__/dev.test.ts +42 -0
  57. package/src/__tests__/fixtures.ts +83 -0
  58. package/src/__tests__/functions-generator.test.ts +101 -0
  59. package/src/__tests__/init.test.ts +59 -0
  60. package/src/__tests__/nextjs-generator.test.ts +97 -0
  61. package/src/__tests__/openapi-generator.test.ts +43 -0
  62. package/src/__tests__/package-manager.test.ts +189 -0
  63. package/src/__tests__/scaffold.test.ts +39 -0
  64. package/src/__tests__/string-utils.test.ts +75 -0
  65. package/src/__tests__/ui-generator.test.ts +144 -0
  66. package/src/cli/commands/create-model.ts +141 -0
  67. package/src/cli/commands/dev.ts +794 -0
  68. package/src/cli/commands/index.ts +8 -0
  69. package/src/cli/commands/init.ts +3363 -0
  70. package/src/cli/commands/provision.ts +193 -0
  71. package/src/cli/commands/scaffold.ts +786 -0
  72. package/src/cli/index.ts +73 -0
  73. package/src/core/config.ts +244 -0
  74. package/src/core/scaffold/functions-generator.ts +674 -0
  75. package/src/core/scaffold/model-parser.ts +627 -0
  76. package/src/core/scaffold/nextjs-generator.ts +217 -0
  77. package/src/core/scaffold/openapi-generator.ts +212 -0
  78. package/src/core/scaffold/ui-generator.ts +945 -0
  79. package/src/database/base-model.ts +184 -0
  80. package/src/database/client.ts +140 -0
  81. package/src/database/repository.ts +104 -0
  82. package/src/database/runtime-check.ts +25 -0
  83. package/src/index.ts +27 -0
  84. package/src/types/index.ts +45 -0
  85. package/src/utils/package-manager.ts +229 -0
  86. package/dist/cli/commands/build.d.ts +0 -6
  87. package/dist/cli/commands/build.d.ts.map +0 -1
  88. package/dist/cli/commands/build.js +0 -177
  89. package/dist/cli/commands/build.js.map +0 -1
  90. package/dist/cli/commands/deploy.d.ts +0 -3
  91. package/dist/cli/commands/deploy.d.ts.map +0 -1
  92. package/dist/cli/commands/deploy.js +0 -147
  93. package/dist/cli/commands/deploy.js.map +0 -1
  94. package/dist/cli/commands/setup.d.ts +0 -6
  95. package/dist/cli/commands/setup.d.ts.map +0 -1
  96. package/dist/cli/commands/setup.js +0 -254
  97. package/dist/cli/commands/setup.js.map +0 -1
package/README.md CHANGED
@@ -1,243 +1,252 @@
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
- # or
44
- pnpm dlx swallowkit init my-app
45
- cd my-app
46
- ```
47
-
48
- The interactive prompts ask for CI/CD provider, Cosmos DB mode, and network settings. You can also specify them as flags to skip prompts entirely:
49
-
50
- ```bash
51
- # Non-interactive mode (useful for VS Code extensions or automation)
52
- npx swallowkit init my-app --cicd github --cosmos-db-mode serverless --vnet outbound
53
- ```
54
-
55
- | Flag | Values | Description |
56
- |------|--------|-------------|
57
- | `--cicd <provider>` | `github`, `azure`, `skip` | CI/CD provider |
58
- | `--cosmos-db-mode <mode>` | `freetier`, `serverless` | Cosmos DB pricing mode |
59
- | `--vnet <option>` | `outbound`, `none` | Network security |
60
-
61
- Omit any flag to be prompted for that value interactively.
62
-
63
- ### 2. Create Models
64
-
65
- You can create multiple models at once:
66
-
67
- ```bash
68
- npx swallowkit create-model category todo
69
- # or
70
- pnpm dlx swallowkit create-model category todo
71
- ```
72
-
73
- This generates `shared/models/category.ts` and `shared/models/todo.ts`. Customize them by adding your required fields:
74
-
75
- ```typescript
76
- // shared/models/category.ts
77
- import { z } from 'zod';
78
-
79
- export const category = z.object({
80
- id: z.string(),
81
- name: z.string().min(1).max(50),
82
- createdAt: z.string().optional(),
83
- updatedAt: z.string().optional(),
84
- });
85
-
86
- export type Category = z.infer<typeof category>;
87
- ```
88
-
89
- For parent-child relationships, use **nested schemas** instead of ID references:
90
-
91
- ```typescript
92
- // shared/models/todo.ts
93
- import { z } from 'zod';
94
- import { category } from './category';
95
-
96
- export const todo = z.object({
97
- id: z.string(),
98
- text: z.string().min(1).max(200),
99
- completed: z.boolean().default(false),
100
- category: category.optional(), // Nested object (not categoryId)
101
- createdAt: z.string().optional(),
102
- updatedAt: z.string().optional(),
103
- });
104
-
105
- export type Todo = z.infer<typeof todo>;
106
- ```
107
-
108
- > **Tip**: Nesting preserves type safety and stores related data together in the document, which is natural for Cosmos DB's document model.
109
-
110
- ### 3. Generate CRUD Code
111
-
112
- ```bash
113
- npx swallowkit scaffold shared/models/todo.ts
114
- # or
115
- pnpm dlx swallowkit scaffold shared/models/todo.ts
116
- ```
117
-
118
- This auto-generates:
119
- - Azure Functions (CRUD endpoints + Cosmos DB bindings)
120
- - ✅ Next.js BFF API Routes (auto-validation + resource inference)
121
- - React Components (type-safe forms)
122
-
123
- ### 4. Start Development Server
124
-
125
- ```bash
126
- npx swallowkit dev
127
- # or
128
- pnpm dlx swallowkit dev
129
- ```
130
-
131
- - Next.js: http://localhost:3000
132
- - Azure Functions: http://localhost:7071
133
-
134
- ### 5. Use from Frontend
135
-
136
- ```typescript
137
- import { api } from '@/lib/api/backend';
138
- import type { Todo } from '@/shared/models/todo';
139
-
140
- // Get all - call BFF endpoint
141
- const todos = await api.get<Todo[]>('/api/todos');
142
-
143
- // Create - validated by backend
144
- const created = await api.post<Todo>('/api/todos', {
145
- text: 'Buy milk',
146
- completed: false
147
- });
148
-
149
- // Update - validated by backend
150
- const updated = await api.put<Todo>('/api/todos/123', { completed: true });
151
-
152
- // Delete
153
- await api.delete('/api/todos/123');
154
- ```
155
-
156
- ## 🏗️ Architecture
157
-
158
- ```
159
- ┌─────────────────────────────────────────────────────────────┐
160
- │ Frontend (React) │
161
- │ - Client Components │
162
- │ - Server Components (SSR) │
163
- └──────────────────────────┬───────────────────────────────────┘
164
- api.post('/api/todos', data)
165
-
166
- ┌─────────────────────────────────────────────────────────────┐
167
- │ BFF Layer (Next.js API Routes) │
168
- - Auto Schema Validation (Zod)
169
- │ - Error Handling
170
- └──────────────────────────┬───────────────────────────────────┘
171
- │ HTTP Request
172
-
173
- ┌─────────────────────────────────────────────────────────────┐
174
- │ Azure Functions (Backend) │
175
- - HTTP Triggers (CRUD)
176
- │ - Zod Validation (Re-check)
177
- │ - Business Logic
178
- │ - Cosmos DB Bindings │
179
- └──────────────────────────┬───────────────────────────────────┘
180
-
181
-
182
- ┌─────────────────────────────────────────────────────────────┐
183
- Azure Cosmos DB
184
- │ - NoSQL Database
185
- │ - Zod Schema Validation
186
- └─────────────────────────────────────────────────────────────┘
187
- ```
188
-
189
- **Key Patterns:**
190
- - **BFF (Backend For Frontend)**: Next.js API Routes proxy to Azure Functions
191
- - **Shared Schemas**: Zod schemas used across frontend, BFF, Functions, and DB
192
- - **Type Safety**: TypeScript types auto-inferred from Zod
193
- - **Managed Identity**: Secure service connections (no connection strings)
194
-
195
- ## 📦 Prerequisites
196
-
197
- - Node.js 22.x
198
- - **pnpm** (recommended): `corepack enable` or `npm install -g pnpm`
199
- - npm also works SwallowKit auto-detects the package manager (if pnpm is installed, it is always preferred)
200
- - Azure Cosmos DB Emulator (local development)
201
- - [Official documentation (vNext recommended)](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux)
202
- - Windows: [Download](https://aka.ms/cosmosdb-emulator)
203
- - Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
204
-
205
- ## 🚀 Deploy to Azure
206
-
207
- Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
208
-
209
- **1. Provision resources (Bicep IaC)**
210
-
211
- ```bash
212
- npx swallowkit provision --resource-group my-app-rg --location japaneast
213
- # or
214
- pnpm dlx swallowkit provision --resource-group my-app-rg --location japaneast
215
- ```
216
-
217
- After provisioning, the required CI/CD secret values are displayed in the terminal. Copy them.
218
-
219
- **2. Push code**
220
-
221
- ```bash
222
- git push origin main
223
- ```
224
-
225
- **3. Cancel the auto-triggered CI/CD run** — it will fail because secrets are not registered yet.
226
-
227
- **4. Register the displayed secret values** in GitHub (Settings → Secrets) or Azure DevOps (Pipelines → Library).
228
-
229
- **5. Manually re-run the CI/CD workflow.**
230
-
231
- See **[Deployment Guide](./docs/deployment-guide.md)** for details.
232
-
233
- ## License
234
-
235
- MIT
236
-
237
- ## 🔗 Related Links
238
-
239
- - [Azure Static Web Apps](https://learn.microsoft.com/en-us/azure/static-web-apps/)
240
- - [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/)
241
- - [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
242
- - [Next.js](https://nextjs.org/)
243
- - [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
+ [![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** - Keep Zod as the source of truth across frontend, BFF, Azure Functions, and Cosmos DB
24
+ - **⚡ CRUD Code Generation** - Auto-generate Azure Functions + Next.js code with `swallowkit scaffold`
25
+ - **🌐 Multi-language Functions Backends** - Choose TypeScript, C#, or Python for Azure Functions during `init`
26
+ - **🧬 OpenAPI Schema Bridge** - For C#/Python backends, `scaffold` exports OpenAPI from Zod and generates backend schema assets
27
+ - **🛡️ Contract Safety** - Keep frontend/BFF contracts aligned with backend implementations through shared Zod or generated OpenAPI-derived models
28
+ - **🎯 BFF Pattern** - Next.js API Routes as BFF layer with auto-validation and resource inference
29
+ - **☁️ Azure Optimized** - Minimal-cost architecture with Static Web Apps + Functions + Cosmos DB
30
+ - **🚀 Easy Deployment** - Auto-generated Bicep IaC + CI/CD workflows
31
+ - **🤖 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
32
+
33
+ ## 📚 Documentation
34
+
35
+ Visit the **[SwallowKit Documentation](https://himanago.github.io/swallowkit/)** for the full docs (also available in [日本語](https://himanago.github.io/swallowkit/ja/)).
36
+
37
+ - **[CLI Reference](https://himanago.github.io/swallowkit/en/cli-reference)** - All commands in detail
38
+ - **[Scaffold Guide](https://himanago.github.io/swallowkit/en/scaffold-guide)** - CRUD code generation
39
+ - **[Zod Schema Sharing Guide](https://himanago.github.io/swallowkit/en/zod-schema-sharing-guide)** - Schema design
40
+ - **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** - Deploy to Azure
41
+
42
+ ## 🚀 Quick Start
43
+
44
+ ### 1. Create Project
45
+
46
+ ```bash
47
+ npx swallowkit init my-app
48
+ # or
49
+ pnpm dlx swallowkit init my-app
50
+ cd my-app
51
+ ```
52
+
53
+ 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:
54
+
55
+ ```bash
56
+ # Non-interactive mode (useful for VS Code extensions or automation)
57
+ npx swallowkit init my-app --cicd github --backend-language python --cosmos-db-mode serverless --vnet outbound
58
+ ```
59
+
60
+ | Flag | Values | Description |
61
+ |------|--------|-------------|
62
+ | `--cicd <provider>` | `github`, `azure`, `skip` | CI/CD provider |
63
+ | `--backend-language <language>` | `typescript`, `csharp`, `python` | Azure Functions backend language |
64
+ | `--cosmos-db-mode <mode>` | `freetier`, `serverless` | Cosmos DB pricing mode |
65
+ | `--vnet <option>` | `outbound`, `none` | Network security |
66
+
67
+ Omit any flag to be prompted for that value interactively.
68
+
69
+ ### 2. Create Models
70
+
71
+ You can create multiple models at once:
72
+
73
+ ```bash
74
+ npx swallowkit create-model category todo
75
+ # or
76
+ pnpm dlx swallowkit create-model category todo
77
+ ```
78
+
79
+ This generates `shared/models/category.ts` and `shared/models/todo.ts`. Customize them by adding your required fields:
80
+
81
+ ```typescript
82
+ // shared/models/category.ts
83
+ import { z } from 'zod';
84
+
85
+ export const category = z.object({
86
+ id: z.string(),
87
+ name: z.string().min(1).max(50),
88
+ createdAt: z.string().optional(),
89
+ updatedAt: z.string().optional(),
90
+ });
91
+
92
+ export type Category = z.infer<typeof category>;
93
+ ```
94
+
95
+ For parent-child relationships, use **nested schemas** instead of ID references:
96
+
97
+ ```typescript
98
+ // shared/models/todo.ts
99
+ import { z } from 'zod';
100
+ import { category } from './category';
101
+
102
+ export const todo = z.object({
103
+ id: z.string(),
104
+ text: z.string().min(1).max(200),
105
+ completed: z.boolean().default(false),
106
+ category: category.optional(), // Nested object (not categoryId)
107
+ createdAt: z.string().optional(),
108
+ updatedAt: z.string().optional(),
109
+ });
110
+
111
+ export type Todo = z.infer<typeof todo>;
112
+ ```
113
+
114
+ > **Tip**: Nesting preserves type safety and stores related data together in the document, which is natural for Cosmos DB's document model.
115
+
116
+ ### 3. Generate CRUD Code
117
+
118
+ ```bash
119
+ npx swallowkit scaffold shared/models/todo.ts
120
+ # or
121
+ pnpm dlx swallowkit scaffold shared/models/todo.ts
122
+ ```
123
+
124
+ This auto-generates:
125
+ - ✅ Azure Functions (CRUD endpoints + Cosmos DB bindings)
126
+ - Next.js BFF API Routes (auto-validation + resource inference)
127
+ - ✅ React Components (type-safe forms)
128
+
129
+ 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/`.
130
+
131
+ ### 4. Start Development Server
132
+
133
+ ```bash
134
+ npx swallowkit dev
135
+ # or
136
+ pnpm dlx swallowkit dev
137
+ ```
138
+
139
+ - Next.js: http://localhost:3000
140
+ - Azure Functions: http://localhost:7071
141
+
142
+ ### 5. Use from Frontend
143
+
144
+ ```typescript
145
+ import { api } from '@/lib/api/backend';
146
+ import type { Todo } from '@/shared/models/todo';
147
+
148
+ // Get all - call BFF endpoint
149
+ const todos = await api.get<Todo[]>('/api/todos');
150
+
151
+ // Create - validated by backend
152
+ const created = await api.post<Todo>('/api/todos', {
153
+ text: 'Buy milk',
154
+ completed: false
155
+ });
156
+
157
+ // Update - validated by backend
158
+ const updated = await api.put<Todo>('/api/todos/123', { completed: true });
159
+
160
+ // Delete
161
+ await api.delete('/api/todos/123');
162
+ ```
163
+
164
+ ## 🏗️ Architecture
165
+
166
+ ```
167
+ ┌─────────────────────────────────────────────────────────────┐
168
+ Frontend (React)
169
+ │ - Client Components
170
+ │ - Server Components (SSR) │
171
+ └──────────────────────────┬───────────────────────────────────┘
172
+ │ api.post('/api/todos', data)
173
+
174
+ ┌─────────────────────────────────────────────────────────────┐
175
+ BFF Layer (Next.js API Routes)
176
+ │ - Auto Schema Validation (Zod)
177
+ │ - Error Handling
178
+ └──────────────────────────┬───────────────────────────────────┘
179
+ │ HTTP Request
180
+
181
+ ┌─────────────────────────────────────────────────────────────┐
182
+ │ Azure Functions (Backend) │
183
+ - HTTP Triggers (CRUD)
184
+ │ - Zod Validation (Re-check)
185
+ │ - Business Logic
186
+ │ - Cosmos DB Bindings │
187
+ └──────────────────────────┬───────────────────────────────────┘
188
+
189
+
190
+ ┌─────────────────────────────────────────────────────────────┐
191
+ │ Azure Cosmos DB
192
+ - NoSQL Database │
193
+ - Zod Schema Validation │
194
+ └─────────────────────────────────────────────────────────────┘
195
+ ```
196
+
197
+ **Key Patterns:**
198
+ - **BFF (Backend For Frontend)**: Next.js API Routes proxy to Azure Functions
199
+ - **Shared Schemas**: Zod schemas stay in `shared/models/` as the source of truth
200
+ - **OpenAPI Bridge for C#/Python**: Non-TypeScript Functions consume generated assets under `functions/generated/`
201
+ - **Contract Safety**: BFF and backend stay aligned through shared Zod or generated backend models
202
+ - **Managed Identity**: Secure service connections (no connection strings)
203
+
204
+ ## 📦 Prerequisites
205
+
206
+ - Node.js 22.x
207
+ - **pnpm** (recommended): `corepack enable` or `npm install -g pnpm`
208
+ - npm also works — SwallowKit auto-detects the package manager (if pnpm is installed, it is always preferred)
209
+ - Azure Cosmos DB Emulator (local development)
210
+ - [Official documentation (vNext recommended)](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux)
211
+ - Windows: [Download](https://aka.ms/cosmosdb-emulator)
212
+ - Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
213
+
214
+ ## 🚀 Deploy to Azure
215
+
216
+ Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
217
+
218
+ **1. Provision resources (Bicep IaC)**
219
+
220
+ ```bash
221
+ npx swallowkit provision --resource-group my-app-rg --location japaneast
222
+ # or
223
+ pnpm dlx swallowkit provision --resource-group my-app-rg --location japaneast
224
+ ```
225
+
226
+ After provisioning, the required CI/CD secret values are displayed in the terminal. Copy them.
227
+
228
+ **2. Push code**
229
+
230
+ ```bash
231
+ git push origin main
232
+ ```
233
+
234
+ **3. Cancel the auto-triggered CI/CD run** — it will fail because secrets are not registered yet.
235
+
236
+ **4. Register the displayed secret values** in GitHub (Settings → Secrets) or Azure DevOps (Pipelines → Library).
237
+
238
+ **5. Manually re-run the CI/CD workflow.**
239
+
240
+ See **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** for details.
241
+
242
+ ## License
243
+
244
+ MIT
245
+
246
+ ## 🔗 Related Links
247
+
248
+ - [Azure Static Web Apps](https://learn.microsoft.com/en-us/azure/static-web-apps/)
249
+ - [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/)
250
+ - [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
251
+ - [Next.js](https://nextjs.org/)
252
+ - [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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"}