swallowkit 1.0.0-beta.2 โ 1.0.0-beta.21
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.
- package/LICENSE +21 -21
- package/README.ja.md +312 -215
- package/README.md +369 -216
- package/dist/__tests__/fixtures.d.ts +22 -0
- package/dist/__tests__/fixtures.d.ts.map +1 -0
- package/dist/__tests__/fixtures.js +146 -0
- package/dist/__tests__/fixtures.js.map +1 -0
- package/dist/cli/commands/add-auth.d.ts +10 -0
- package/dist/cli/commands/add-auth.d.ts.map +1 -0
- package/dist/cli/commands/add-auth.js +444 -0
- package/dist/cli/commands/add-auth.js.map +1 -0
- package/dist/cli/commands/add-connector.d.ts +20 -0
- package/dist/cli/commands/add-connector.d.ts.map +1 -0
- package/dist/cli/commands/add-connector.js +163 -0
- package/dist/cli/commands/add-connector.js.map +1 -0
- package/dist/cli/commands/create-model.d.ts +1 -4
- package/dist/cli/commands/create-model.d.ts.map +1 -1
- package/dist/cli/commands/create-model.js +21 -82
- package/dist/cli/commands/create-model.js.map +1 -1
- package/dist/cli/commands/dev-seeds.d.ts +35 -0
- package/dist/cli/commands/dev-seeds.d.ts.map +1 -0
- package/dist/cli/commands/dev-seeds.js +292 -0
- package/dist/cli/commands/dev-seeds.js.map +1 -0
- package/dist/cli/commands/dev.d.ts +19 -0
- package/dist/cli/commands/dev.d.ts.map +1 -1
- package/dist/cli/commands/dev.js +476 -117
- package/dist/cli/commands/dev.js.map +1 -1
- package/dist/cli/commands/index.d.ts +1 -0
- package/dist/cli/commands/index.d.ts.map +1 -1
- package/dist/cli/commands/index.js +3 -1
- package/dist/cli/commands/index.js.map +1 -1
- package/dist/cli/commands/init.d.ts +13 -0
- package/dist/cli/commands/init.d.ts.map +1 -1
- package/dist/cli/commands/init.js +2627 -1708
- package/dist/cli/commands/init.js.map +1 -1
- package/dist/cli/commands/scaffold.d.ts +3 -0
- package/dist/cli/commands/scaffold.d.ts.map +1 -1
- package/dist/cli/commands/scaffold.js +617 -129
- package/dist/cli/commands/scaffold.js.map +1 -1
- package/dist/cli/index.d.ts +5 -1
- package/dist/cli/index.d.ts.map +1 -1
- package/dist/cli/index.js +164 -42
- package/dist/cli/index.js.map +1 -1
- package/dist/core/config.d.ts +8 -2
- package/dist/core/config.d.ts.map +1 -1
- package/dist/core/config.js +90 -4
- package/dist/core/config.js.map +1 -1
- package/dist/core/mock/connector-mock-server.d.ts +101 -0
- package/dist/core/mock/connector-mock-server.d.ts.map +1 -0
- package/dist/core/mock/connector-mock-server.js +480 -0
- package/dist/core/mock/connector-mock-server.js.map +1 -0
- package/dist/core/mock/zod-mock-generator.d.ts +14 -0
- package/dist/core/mock/zod-mock-generator.d.ts.map +1 -0
- package/dist/core/mock/zod-mock-generator.js +163 -0
- package/dist/core/mock/zod-mock-generator.js.map +1 -0
- package/dist/core/operations/create-model.d.ts +15 -0
- package/dist/core/operations/create-model.d.ts.map +1 -0
- package/dist/core/operations/create-model.js +171 -0
- package/dist/core/operations/create-model.js.map +1 -0
- package/dist/core/operations/runtime.d.ts +32 -0
- package/dist/core/operations/runtime.d.ts.map +1 -0
- package/dist/core/operations/runtime.js +225 -0
- package/dist/core/operations/runtime.js.map +1 -0
- package/dist/core/operations/scaffold-machine.d.ts +16 -0
- package/dist/core/operations/scaffold-machine.d.ts.map +1 -0
- package/dist/core/operations/scaffold-machine.js +63 -0
- package/dist/core/operations/scaffold-machine.js.map +1 -0
- package/dist/core/project/manifest.d.ts +92 -0
- package/dist/core/project/manifest.d.ts.map +1 -0
- package/dist/core/project/manifest.js +321 -0
- package/dist/core/project/manifest.js.map +1 -0
- package/dist/core/project/validation.d.ts +20 -0
- package/dist/core/project/validation.d.ts.map +1 -0
- package/dist/core/project/validation.js +204 -0
- package/dist/core/project/validation.js.map +1 -0
- package/dist/core/scaffold/auth-generator.d.ts +38 -0
- package/dist/core/scaffold/auth-generator.d.ts.map +1 -0
- package/dist/core/scaffold/auth-generator.js +1244 -0
- package/dist/core/scaffold/auth-generator.js.map +1 -0
- package/dist/core/scaffold/connector-functions-generator.d.ts +41 -0
- package/dist/core/scaffold/connector-functions-generator.d.ts.map +1 -0
- package/dist/core/scaffold/connector-functions-generator.js +1027 -0
- package/dist/core/scaffold/connector-functions-generator.js.map +1 -0
- package/dist/core/scaffold/functions-generator.d.ts +7 -1
- package/dist/core/scaffold/functions-generator.d.ts.map +1 -1
- package/dist/core/scaffold/functions-generator.js +920 -213
- package/dist/core/scaffold/functions-generator.js.map +1 -1
- package/dist/core/scaffold/model-parser.d.ts +20 -1
- package/dist/core/scaffold/model-parser.d.ts.map +1 -1
- package/dist/core/scaffold/model-parser.js +329 -135
- package/dist/core/scaffold/model-parser.js.map +1 -1
- package/dist/core/scaffold/nextjs-generator.d.ts +8 -0
- package/dist/core/scaffold/nextjs-generator.d.ts.map +1 -1
- package/dist/core/scaffold/nextjs-generator.js +314 -182
- package/dist/core/scaffold/nextjs-generator.js.map +1 -1
- package/dist/core/scaffold/openapi-generator.d.ts +3 -0
- package/dist/core/scaffold/openapi-generator.d.ts.map +1 -0
- package/dist/core/scaffold/openapi-generator.js +190 -0
- package/dist/core/scaffold/openapi-generator.js.map +1 -0
- package/dist/core/scaffold/ui-generator.d.ts +10 -4
- package/dist/core/scaffold/ui-generator.d.ts.map +1 -1
- package/dist/core/scaffold/ui-generator.js +768 -663
- package/dist/core/scaffold/ui-generator.js.map +1 -1
- package/dist/database/base-model.d.ts +3 -3
- package/dist/database/base-model.js +3 -3
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/machine/contracts.d.ts +16 -0
- package/dist/machine/contracts.d.ts.map +1 -0
- package/dist/machine/contracts.js +3 -0
- package/dist/machine/contracts.js.map +1 -0
- package/dist/machine/errors.d.ts +11 -0
- package/dist/machine/errors.d.ts.map +1 -0
- package/dist/machine/errors.js +34 -0
- package/dist/machine/errors.js.map +1 -0
- package/dist/machine/index.d.ts +3 -0
- package/dist/machine/index.d.ts.map +1 -0
- package/dist/machine/index.js +156 -0
- package/dist/machine/index.js.map +1 -0
- package/dist/mcp/index.d.ts +25 -0
- package/dist/mcp/index.d.ts.map +1 -0
- package/dist/mcp/index.js +184 -0
- package/dist/mcp/index.js.map +1 -0
- package/dist/types/index.d.ts +65 -0
- package/dist/types/index.d.ts.map +1 -1
- package/dist/utils/package-manager.d.ts +109 -0
- package/dist/utils/package-manager.d.ts.map +1 -0
- package/dist/utils/package-manager.js +215 -0
- package/dist/utils/package-manager.js.map +1 -0
- package/package.json +85 -73
- package/src/__tests__/__snapshots__/functions-generator.test.ts.snap +1139 -0
- package/src/__tests__/__snapshots__/nextjs-generator.test.ts.snap +194 -0
- package/src/__tests__/__snapshots__/ui-generator.test.ts.snap +532 -0
- package/src/__tests__/auth.test.ts +654 -0
- package/src/__tests__/config.test.ts +263 -0
- package/src/__tests__/connector-functions-generator.test.ts +288 -0
- package/src/__tests__/connector-mock-server.test.ts +439 -0
- package/src/__tests__/connector-model-bff.test.ts +162 -0
- package/src/__tests__/dev-seeds.test.ts +112 -0
- package/src/__tests__/dev.test.ts +154 -0
- package/src/__tests__/fixtures.ts +144 -0
- package/src/__tests__/functions-generator.test.ts +237 -0
- package/src/__tests__/init.test.ts +80 -0
- package/src/__tests__/machine.test.ts +212 -0
- package/src/__tests__/mcp.test.ts +56 -0
- package/src/__tests__/model-parser.test.ts +72 -0
- package/src/__tests__/nextjs-generator.test.ts +97 -0
- package/src/__tests__/openapi-generator.test.ts +43 -0
- package/src/__tests__/package-manager.test.ts +189 -0
- package/src/__tests__/scaffold.test.ts +39 -0
- package/src/__tests__/string-utils.test.ts +75 -0
- package/src/__tests__/ui-generator.test.ts +144 -0
- package/src/__tests__/zod-mock-generator.test.ts +132 -0
- package/src/cli/commands/add-auth.ts +500 -0
- package/src/cli/commands/add-connector.ts +158 -0
- package/src/cli/commands/create-model.ts +62 -0
- package/src/cli/commands/dev-seeds.ts +358 -0
- package/src/cli/commands/dev.ts +962 -0
- package/src/cli/commands/index.ts +9 -0
- package/src/cli/commands/init.ts +3371 -0
- package/src/cli/commands/provision.ts +193 -0
- package/src/cli/commands/scaffold.ts +1211 -0
- package/src/cli/index.ts +193 -0
- package/src/core/config.ts +308 -0
- package/src/core/mock/connector-mock-server.ts +555 -0
- package/src/core/mock/zod-mock-generator.ts +205 -0
- package/src/core/operations/create-model.ts +174 -0
- package/src/core/operations/runtime.ts +235 -0
- package/src/core/operations/scaffold-machine.ts +91 -0
- package/src/core/project/manifest.ts +402 -0
- package/src/core/project/validation.ts +221 -0
- package/src/core/scaffold/auth-generator.ts +1284 -0
- package/src/core/scaffold/connector-functions-generator.ts +1128 -0
- package/src/core/scaffold/functions-generator.ts +970 -0
- package/src/core/scaffold/model-parser.ts +841 -0
- package/src/core/scaffold/nextjs-generator.ts +370 -0
- package/src/core/scaffold/openapi-generator.ts +212 -0
- package/src/core/scaffold/ui-generator.ts +1061 -0
- package/src/database/base-model.ts +184 -0
- package/src/database/client.ts +140 -0
- package/src/database/repository.ts +104 -0
- package/src/database/runtime-check.ts +25 -0
- package/src/index.ts +27 -0
- package/src/machine/contracts.ts +17 -0
- package/src/machine/errors.ts +34 -0
- package/src/machine/index.ts +173 -0
- package/src/mcp/index.ts +185 -0
- package/src/types/index.ts +134 -0
- package/src/utils/package-manager.ts +229 -0
package/README.md
CHANGED
|
@@ -1,216 +1,369 @@
|
|
|
1
|
-
# SwallowKit
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/swallowkit)
|
|
4
|
-
[](https://www.npmjs.com/package/swallowkit)
|
|
5
|
-
[](https://www.npmjs.com/package/swallowkit)
|
|
4
|
+
[](https://www.npmjs.com/package/swallowkit)
|
|
5
|
+
[](https://marketplace.visualstudio.com/items?itemName=himanago.swallowkit-vscode)
|
|
6
|
+
[](./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
|
+
- **๐ง MCP + Machine Interface** - `swallowkit machine ...` exposes deterministic JSON inspection / validation / generation commands, and `swallowkit-mcp` exposes the same capabilities over MCP stdio
|
|
34
|
+
- **๐ External Data Connectors** - Integrate MySQL, PostgreSQL, REST APIs, and other external data sources alongside Cosmos DB โ same Zod-driven scaffold workflow with full type safety
|
|
35
|
+
- **๐ Authentication & Authorization** - Built-in support for custom JWT auth (with external RDB user stores) and role-based access control per model โ with planned Static Web Apps auth integration
|
|
36
|
+
- **๐งฉ [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
|
|
37
|
+
|
|
38
|
+
## ๐ Documentation
|
|
39
|
+
|
|
40
|
+
Visit the **[SwallowKit Documentation](https://himanago.github.io/swallowkit/)** for the full docs (also available in [ๆฅๆฌ่ช](https://himanago.github.io/swallowkit/ja/)).
|
|
41
|
+
|
|
42
|
+
- **[CLI Reference](https://himanago.github.io/swallowkit/en/cli-reference)** - All commands in detail
|
|
43
|
+
- **[Scaffold Guide](https://himanago.github.io/swallowkit/en/scaffold-guide)** - CRUD code generation
|
|
44
|
+
- **[Connector Guide](https://himanago.github.io/swallowkit/en/connector-guide)** - External data source integration
|
|
45
|
+
- **[Authentication Guide](https://himanago.github.io/swallowkit/en/auth-guide)** - Authentication and role-based access control
|
|
46
|
+
- **[Zod Schema Sharing Guide](https://himanago.github.io/swallowkit/en/zod-schema-sharing-guide)** - Schema design
|
|
47
|
+
- **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** - Deploy to Azure
|
|
48
|
+
|
|
49
|
+
## ๐ Quick Start
|
|
50
|
+
|
|
51
|
+
### 1. Create Project
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npx swallowkit init my-app
|
|
55
|
+
# or
|
|
56
|
+
pnpm dlx swallowkit init my-app
|
|
57
|
+
cd my-app
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
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:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
# Non-interactive mode (useful for VS Code extensions or automation)
|
|
64
|
+
npx swallowkit init my-app --cicd github --backend-language python --cosmos-db-mode serverless --vnet outbound
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
| Flag | Values | Description |
|
|
68
|
+
|------|--------|-------------|
|
|
69
|
+
| `--cicd <provider>` | `github`, `azure`, `skip` | CI/CD provider |
|
|
70
|
+
| `--backend-language <language>` | `typescript`, `csharp`, `python` | Azure Functions backend language |
|
|
71
|
+
| `--cosmos-db-mode <mode>` | `freetier`, `serverless` | Cosmos DB pricing mode |
|
|
72
|
+
| `--vnet <option>` | `outbound`, `none` | Network security |
|
|
73
|
+
|
|
74
|
+
Omit any flag to be prompted for that value interactively.
|
|
75
|
+
|
|
76
|
+
### 2. Create Models
|
|
77
|
+
|
|
78
|
+
You can create multiple models at once:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
npx swallowkit create-model category todo
|
|
82
|
+
# or
|
|
83
|
+
pnpm dlx swallowkit create-model category todo
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
This generates `shared/models/category.ts` and `shared/models/todo.ts`. Customize them by adding your required fields:
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
// shared/models/category.ts
|
|
90
|
+
import { z } from 'zod';
|
|
91
|
+
|
|
92
|
+
export const category = z.object({
|
|
93
|
+
id: z.string(),
|
|
94
|
+
name: z.string().min(1).max(50),
|
|
95
|
+
createdAt: z.string().optional(),
|
|
96
|
+
updatedAt: z.string().optional(),
|
|
97
|
+
});
|
|
98
|
+
|
|
99
|
+
export type Category = z.infer<typeof category>;
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
For parent-child relationships, use **nested schemas** instead of ID references:
|
|
103
|
+
|
|
104
|
+
```typescript
|
|
105
|
+
// shared/models/todo.ts
|
|
106
|
+
import { z } from 'zod';
|
|
107
|
+
import { category } from './category';
|
|
108
|
+
|
|
109
|
+
export const todo = z.object({
|
|
110
|
+
id: z.string(),
|
|
111
|
+
text: z.string().min(1).max(200),
|
|
112
|
+
completed: z.boolean().default(false),
|
|
113
|
+
category: category.optional(), // Nested object (not categoryId)
|
|
114
|
+
createdAt: z.string().optional(),
|
|
115
|
+
updatedAt: z.string().optional(),
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
export type Todo = z.infer<typeof todo>;
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
> **Tip**: Nesting preserves type safety and stores related data together in the document, which is natural for Cosmos DB's document model.
|
|
122
|
+
|
|
123
|
+
### 3. Generate CRUD Code
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npx swallowkit scaffold shared/models/todo.ts
|
|
127
|
+
# or
|
|
128
|
+
pnpm dlx swallowkit scaffold shared/models/todo.ts
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
This auto-generates:
|
|
132
|
+
- โ
Azure Functions (CRUD endpoints + Cosmos DB bindings)
|
|
133
|
+
- โ
Next.js BFF API Routes (auto-validation + resource inference)
|
|
134
|
+
- โ
React Components (type-safe forms)
|
|
135
|
+
|
|
136
|
+
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/`.
|
|
137
|
+
|
|
138
|
+
### 4. Start Development Server
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
npx swallowkit dev
|
|
142
|
+
# or
|
|
143
|
+
pnpm dlx swallowkit dev
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
- Next.js: http://localhost:3000
|
|
147
|
+
- Azure Functions: http://localhost:7071
|
|
148
|
+
|
|
149
|
+
If you want to replace Cosmos DB Emulator data before startup, generate an environment template and then launch `dev` with that environment:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
npx swallowkit create-dev-seeds local
|
|
153
|
+
# edit dev-seeds/local/*.json
|
|
154
|
+
npx swallowkit dev --seed-env local
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
This workflow is designed for local debugging against the Cosmos DB Emulator:
|
|
158
|
+
|
|
159
|
+
- `create-dev-seeds <environment>` generates one JSON template per schema under `dev-seeds/<environment>/`
|
|
160
|
+
- each file name maps to a schema/container, for example `shared/models/todo.ts` -> `dev-seeds/local/todo.json` -> `Todos`
|
|
161
|
+
- when you start `dev --seed-env <environment>`, SwallowKit replaces the existing data for each matching container with the JSON documents from that environment
|
|
162
|
+
- containers without a matching JSON file are left untouched
|
|
163
|
+
- if `--seed-env` is omitted, or `dev-seeds/<environment>/` does not exist, current emulator data is preserved
|
|
164
|
+
|
|
165
|
+
Example file layout:
|
|
166
|
+
|
|
167
|
+
```text
|
|
168
|
+
dev-seeds/
|
|
169
|
+
local/
|
|
170
|
+
todo.json
|
|
171
|
+
category.json
|
|
172
|
+
staging-debug/
|
|
173
|
+
todo.json
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Each `{schema}.json` file can contain either a single JSON object or an array of JSON objects. Every document must include an `id`:
|
|
177
|
+
|
|
178
|
+
```json
|
|
179
|
+
[
|
|
180
|
+
{
|
|
181
|
+
"id": "seed-todo-001",
|
|
182
|
+
"name": "Seed todo one",
|
|
183
|
+
"createdAt": "2026-03-21T00:00:00.000Z",
|
|
184
|
+
"updatedAt": "2026-03-21T00:00:00.000Z"
|
|
185
|
+
},
|
|
186
|
+
{
|
|
187
|
+
"id": "seed-todo-002",
|
|
188
|
+
"name": "Seed todo two",
|
|
189
|
+
"createdAt": "2026-03-21T00:00:01.000Z",
|
|
190
|
+
"updatedAt": "2026-03-21T00:00:01.000Z"
|
|
191
|
+
}
|
|
192
|
+
]
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Recommended workflow:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
npx swallowkit create-model todo
|
|
199
|
+
npx swallowkit scaffold shared/models/todo.ts
|
|
200
|
+
npx swallowkit create-dev-seeds local
|
|
201
|
+
# edit dev-seeds/local/todo.json
|
|
202
|
+
npx swallowkit dev --seed-env local
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### 5. Use from Frontend
|
|
206
|
+
|
|
207
|
+
```typescript
|
|
208
|
+
import { api } from '@/lib/api/backend';
|
|
209
|
+
import type { Todo } from '@/shared/models/todo';
|
|
210
|
+
|
|
211
|
+
// Get all - call BFF endpoint
|
|
212
|
+
const todos = await api.get<Todo[]>('/api/todos');
|
|
213
|
+
|
|
214
|
+
// Create - validated by backend
|
|
215
|
+
const created = await api.post<Todo>('/api/todos', {
|
|
216
|
+
text: 'Buy milk',
|
|
217
|
+
completed: false
|
|
218
|
+
});
|
|
219
|
+
|
|
220
|
+
// Update - validated by backend
|
|
221
|
+
const updated = await api.put<Todo>('/api/todos/123', { completed: true });
|
|
222
|
+
|
|
223
|
+
// Delete
|
|
224
|
+
await api.delete('/api/todos/123');
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### 6. Connect External Data Sources (Optional)
|
|
228
|
+
|
|
229
|
+
SwallowKit supports **connectors** for integrating external RDB databases and REST APIs alongside Cosmos DB, using the same Zod-driven workflow:
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
# Register a connector
|
|
233
|
+
npx swallowkit add-connector mysql --type rdb --provider mysql --connection-env MYSQL_CONNECTION_STRING
|
|
234
|
+
|
|
235
|
+
# Create a connector-aware model
|
|
236
|
+
npx swallowkit create-model user --connector mysql
|
|
237
|
+
# edit shared/models/user.ts (customize schema + connectorConfig)
|
|
238
|
+
|
|
239
|
+
# Scaffold generates connector-specific Functions code
|
|
240
|
+
npx swallowkit scaffold shared/models/user.ts
|
|
241
|
+
|
|
242
|
+
# Develop locally with mock data (no real MySQL needed)
|
|
243
|
+
npx swallowkit dev --mock-connectors
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
The frontend and BFF layer are completely transparent to data source differences โ `callFunction()` works identically for Cosmos DB and connector models. See the **[Connector Guide](https://himanago.github.io/swallowkit/en/connector-guide)** for details.
|
|
247
|
+
|
|
248
|
+
## ๐ค AI / MCP Integration
|
|
249
|
+
|
|
250
|
+
SwallowKit provides a machine-readable CLI surface for coding agents and MCP adapters. Instead of letting AI guess raw filesystem changes, it can go through SwallowKit's official generators, inspectors, and validators.
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
# Inspect framework-owned project metadata
|
|
254
|
+
npx swallowkit machine inspect project
|
|
255
|
+
|
|
256
|
+
# Validate SwallowKit conventions and generated artifacts
|
|
257
|
+
npx swallowkit machine validate project
|
|
258
|
+
|
|
259
|
+
# Generate through the official machine interface
|
|
260
|
+
npx swallowkit machine generate model todo --overwrite never
|
|
261
|
+
npx swallowkit machine generate scaffold todo --api-only
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
`swallowkit machine` is:
|
|
265
|
+
|
|
266
|
+
- non-interactive
|
|
267
|
+
- deterministic
|
|
268
|
+
- JSON-only on stdout
|
|
269
|
+
- structured on success and failure
|
|
270
|
+
|
|
271
|
+
For MCP clients, use the bundled stdio server:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
npx swallowkit-mcp
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
The MCP server is intentionally a thin adapter with explicit tools only. It delegates real work to the machine CLI.
|
|
278
|
+
|
|
279
|
+
## ๐๏ธ Architecture
|
|
280
|
+
|
|
281
|
+
```
|
|
282
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
283
|
+
โ Frontend (React) โ
|
|
284
|
+
โ - Client Components โ
|
|
285
|
+
โ - Server Components (SSR) โ
|
|
286
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
287
|
+
โ api.post('/api/todos', data)
|
|
288
|
+
โผ
|
|
289
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
290
|
+
โ BFF Layer (Next.js API Routes) โ
|
|
291
|
+
โ - Auto Schema Validation (Zod) โ
|
|
292
|
+
โ - Error Handling โ
|
|
293
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
294
|
+
โ HTTP Request
|
|
295
|
+
โผ
|
|
296
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
297
|
+
โ Azure Functions (Backend) โ
|
|
298
|
+
โ - HTTP Triggers (CRUD) โ
|
|
299
|
+
โ - Zod Validation (Re-check) โ
|
|
300
|
+
โ - Business Logic โ
|
|
301
|
+
โ - Data Source Bindings โ
|
|
302
|
+
โโโโโโโโโโโโฌโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ
|
|
303
|
+
โ โ โ
|
|
304
|
+
โผ โผ โผ
|
|
305
|
+
โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
|
|
306
|
+
โ Azure Cosmos โ โ External โ โ External SaaS โ
|
|
307
|
+
โ DB (Default) โ โ RDB (MySQL โ โ APIs (REST) โ
|
|
308
|
+
โ โ โ PostgreSQL) โ โ โ
|
|
309
|
+
โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
**Key Patterns:**
|
|
313
|
+
- **BFF (Backend For Frontend)**: Next.js API Routes proxy to Azure Functions
|
|
314
|
+
- **Shared Schemas**: Zod schemas stay in `shared/models/` as the source of truth
|
|
315
|
+
- **OpenAPI Bridge for C#/Python**: Non-TypeScript Functions consume generated assets under `functions/generated/`
|
|
316
|
+
- **External Connectors**: MySQL, PostgreSQL, REST APIs โ scaffold-generated Functions with the same BFF pattern
|
|
317
|
+
- **Contract Safety**: BFF and backend stay aligned through shared Zod or generated backend models
|
|
318
|
+
- **Managed Identity**: Secure service connections (no connection strings)
|
|
319
|
+
|
|
320
|
+
## ๐ฆ Prerequisites
|
|
321
|
+
|
|
322
|
+
- Node.js 22.x
|
|
323
|
+
- **pnpm** (recommended): `corepack enable` or `npm install -g pnpm`
|
|
324
|
+
- npm also works โ SwallowKit auto-detects the package manager (if pnpm is installed, it is always preferred)
|
|
325
|
+
- Azure Cosmos DB Emulator (local development)
|
|
326
|
+
- [Official documentation (vNext recommended)](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux)
|
|
327
|
+
- Windows: [Download](https://aka.ms/cosmosdb-emulator)
|
|
328
|
+
- Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
|
|
329
|
+
|
|
330
|
+
## ๐ Deploy to Azure
|
|
331
|
+
|
|
332
|
+
Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
|
|
333
|
+
|
|
334
|
+
**1. Provision resources (Bicep IaC)**
|
|
335
|
+
|
|
336
|
+
```bash
|
|
337
|
+
npx swallowkit provision --resource-group my-app-rg
|
|
338
|
+
# or
|
|
339
|
+
pnpm dlx swallowkit provision --resource-group my-app-rg
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
The command prompts you to choose the primary region and the Static Web App region. After provisioning, the terminal displays the CI/CD values you need for setup. Copy them.
|
|
343
|
+
|
|
344
|
+
**2. Push code**
|
|
345
|
+
|
|
346
|
+
```bash
|
|
347
|
+
git push origin main
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
**3. Cancel the auto-triggered CI/CD run** โ it will fail because secrets are not registered yet.
|
|
351
|
+
|
|
352
|
+
**4. Register the displayed secrets / variables** in GitHub (Settings โ Secrets) or Azure DevOps (Pipelines โ Library).
|
|
353
|
+
|
|
354
|
+
**5. Manually re-run the CI/CD workflow.**
|
|
355
|
+
|
|
356
|
+
See **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** for details.
|
|
357
|
+
|
|
358
|
+
## License
|
|
359
|
+
|
|
360
|
+
MIT
|
|
361
|
+
|
|
362
|
+
## ๐ Related Links
|
|
363
|
+
|
|
364
|
+
- [SwallowKit VS Code Extension](https://marketplace.visualstudio.com/items?itemName=himanago.swallowkit-vscode)
|
|
365
|
+
- [Azure Static Web Apps](https://learn.microsoft.com/en-us/azure/static-web-apps/)
|
|
366
|
+
- [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/)
|
|
367
|
+
- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
|
|
368
|
+
- [Next.js](https://nextjs.org/)
|
|
369
|
+
- [Zod](https://zod.dev/)
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { ModelInfo } from "../core/scaffold/model-parser";
|
|
2
|
+
/**
|
|
3
|
+
* ใในใ็จใฎๅบๆฌ็ใช ModelInfo ใใฃใฏในใใฃ
|
|
4
|
+
*/
|
|
5
|
+
export declare function createBasicModelInfo(overrides?: Partial<ModelInfo>): ModelInfo;
|
|
6
|
+
/**
|
|
7
|
+
* RDB ใณใใฏใฟ (read-only) ไปใใฎ ModelInfo ใใฃใฏในใใฃ
|
|
8
|
+
*/
|
|
9
|
+
export declare function createRdbConnectorModelInfo(overrides?: Partial<ModelInfo>): ModelInfo;
|
|
10
|
+
/**
|
|
11
|
+
* API ใณใใฏใฟ (read-write) ไปใใฎ ModelInfo ใใฃใฏในใใฃ
|
|
12
|
+
*/
|
|
13
|
+
export declare function createApiConnectorModelInfo(overrides?: Partial<ModelInfo>): ModelInfo;
|
|
14
|
+
/**
|
|
15
|
+
* ๅค้จใญใผใๅซใ ModelInfo ใใฃใฏในใใฃ
|
|
16
|
+
*/
|
|
17
|
+
export declare function createModelInfoWithForeignKey(): ModelInfo;
|
|
18
|
+
/**
|
|
19
|
+
* enum ใใฃใผใซใใๅซใ ModelInfo ใใฃใฏในใใฃ
|
|
20
|
+
*/
|
|
21
|
+
export declare function createModelInfoWithEnum(): ModelInfo;
|
|
22
|
+
//# 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,CAqB9E;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAuBrF;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CA2BrF;AAED;;GAEG;AACH,wBAAgB,6BAA6B,IAAI,SAAS,CAqBzD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,SAAS,CA0BnD"}
|