swallowkit 1.0.0-beta.36 → 1.0.0-beta.37
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/README.ja.md +84 -284
- package/README.md +85 -338
- package/dist/cli/commands/init.d.ts +7 -0
- package/dist/cli/commands/init.d.ts.map +1 -1
- package/dist/cli/commands/init.js +135 -31
- package/dist/cli/commands/init.js.map +1 -1
- package/package.json +1 -1
- package/src/__tests__/init.test.ts +21 -0
- package/src/cli/commands/init.ts +149 -38
package/README.md
CHANGED
|
@@ -7,111 +7,106 @@
|
|
|
7
7
|
|
|
8
8
|
English | [日本語](./README.ja.md)
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Schema-driven application scaffolding for Next.js and Azure.
|
|
11
11
|
|
|
12
|
-
SwallowKit
|
|
12
|
+
SwallowKit helps you build maintainable full-stack applications on Azure by using shared Zod schemas as the source of truth. From one schema definition, it can generate frontend forms, BFF routes, Azure Functions backends, OpenAPI contracts, infrastructure templates, and AI-agent-friendly project metadata.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
It is designed for developers who want to build Next.js applications on Azure without letting the frontend, backend, database model, validation rules, and deployment configuration drift apart.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
## 🎯 Why SwallowKit?
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
AI can generate application code quickly. Frameworks can hide complexity nicely. But production applications still need explicit architecture.
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
In a typical full-stack application, the same domain model is repeated across many places:
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
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
|
-
- **🧪 Reusable Dev Seeds** - Turn real Cosmos DB Emulator data into reusable seed files for demos, regression checks, onboarding, and local verification
|
|
37
|
-
- **🧩 [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
|
|
22
|
+
- frontend form types
|
|
23
|
+
- client-side validation
|
|
24
|
+
- BFF request and response models
|
|
25
|
+
- backend DTOs
|
|
26
|
+
- API contracts
|
|
27
|
+
- database entities
|
|
28
|
+
- seed data
|
|
29
|
+
- infrastructure and deployment configuration
|
|
38
30
|
|
|
39
|
-
|
|
31
|
+
As the application grows, these layers often drift apart. SwallowKit reduces that drift by making the schema explicit and using it to generate the surrounding application structure.
|
|
40
32
|
|
|
41
|
-
|
|
33
|
+
**SwallowKit is not a full-stack framework that hides everything behind magic. It is a scaffolding toolkit that generates readable, editable, and replaceable code.**
|
|
42
34
|
|
|
43
|
-
|
|
44
|
-
- **[Scaffold Guide](https://himanago.github.io/swallowkit/en/scaffold-guide)** - CRUD code generation
|
|
45
|
-
- **[Connector Guide](https://himanago.github.io/swallowkit/en/connector-guide)** - External data source integration
|
|
46
|
-
- **[Authentication Guide](https://himanago.github.io/swallowkit/en/auth-guide)** - Authentication and role-based access control
|
|
47
|
-
- **[Zod Schema Sharing Guide](https://himanago.github.io/swallowkit/en/zod-schema-sharing-guide)** - Schema design
|
|
48
|
-
- **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** - Deploy to Azure
|
|
35
|
+
## ✨ What it gives you
|
|
49
36
|
|
|
50
|
-
|
|
37
|
+
- **Shared Zod schemas** as the source of truth
|
|
38
|
+
- **CRUD scaffolding** for Next.js, BFF routes, Azure Functions, and UI components
|
|
39
|
+
- **Azure-ready infrastructure** using Bicep
|
|
40
|
+
- **Multi-language Azure Functions** backends (TypeScript, C#, Python)
|
|
41
|
+
- **Local development helpers** and seed data
|
|
42
|
+
- **AI/MCP-friendly** project metadata and commands
|
|
43
|
+
- **VS Code extension** support
|
|
51
44
|
|
|
52
|
-
|
|
45
|
+
## 🏗️ Typical architecture
|
|
53
46
|
|
|
54
|
-
|
|
55
|
-
npx swallowkit init my-app
|
|
56
|
-
# or
|
|
57
|
-
pnpm dlx swallowkit init my-app
|
|
58
|
-
cd my-app
|
|
59
|
-
```
|
|
47
|
+
SwallowKit is optimized for applications built with:
|
|
60
48
|
|
|
61
|
-
|
|
49
|
+
- Next.js
|
|
50
|
+
- Azure Static Web Apps
|
|
51
|
+
- Azure Functions
|
|
52
|
+
- Azure Cosmos DB
|
|
53
|
+
- Azure Bicep
|
|
54
|
+
- GitHub Actions or Azure Pipelines
|
|
62
55
|
|
|
63
|
-
|
|
64
|
-
# Non-interactive mode (useful for VS Code extensions or automation)
|
|
65
|
-
npx swallowkit init my-app --cicd github --backend-language python --cosmos-db-mode serverless --vnet outbound
|
|
66
|
-
```
|
|
56
|
+
The default architecture follows a BFF pattern:
|
|
67
57
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
|
71
|
-
|
|
72
|
-
|
|
|
73
|
-
|
|
58
|
+
```
|
|
59
|
+
Browser
|
|
60
|
+
|
|
|
61
|
+
Next.js frontend
|
|
62
|
+
|
|
|
63
|
+
Next.js BFF routes
|
|
64
|
+
|
|
|
65
|
+
Azure Functions API
|
|
66
|
+
|
|
|
67
|
+
Azure Cosmos DB
|
|
68
|
+
```
|
|
74
69
|
|
|
75
|
-
|
|
70
|
+
The BFF layer keeps frontend code simple while allowing backend services, authentication, authorization, and cloud resources to evolve independently.
|
|
76
71
|
|
|
77
|
-
|
|
72
|
+
> **Note**: This project is in active development. APIs may change in future versions.
|
|
78
73
|
|
|
79
|
-
|
|
74
|
+
## 📚 Documentation
|
|
80
75
|
|
|
81
|
-
|
|
82
|
-
npx swallowkit create-model category todo
|
|
83
|
-
# or
|
|
84
|
-
pnpm dlx swallowkit create-model category todo
|
|
85
|
-
```
|
|
76
|
+
Visit the **[SwallowKit Documentation](https://himanago.github.io/swallowkit/)** for the full docs (also available in [日本語](https://himanago.github.io/swallowkit/ja/)).
|
|
86
77
|
|
|
87
|
-
|
|
78
|
+
- **[Getting Started](https://himanago.github.io/swallowkit/en/getting-started)** - First project setup
|
|
79
|
+
- **[Core Concepts](https://himanago.github.io/swallowkit/en/concepts)** - Schema-centric architecture
|
|
80
|
+
- **[Scaffold Guide](https://himanago.github.io/swallowkit/en/scaffold-guide)** - CRUD code generation
|
|
81
|
+
- **[Local Development](https://himanago.github.io/swallowkit/en/dev-guide)** - Dev server, seeds, mock connectors
|
|
82
|
+
- **[Deployment Guide](https://himanago.github.io/swallowkit/en/deployment-guide)** - Deploy to Azure
|
|
83
|
+
- **[AI / MCP Guide](https://himanago.github.io/swallowkit/en/ai-mcp-guide)** - AI-agent integration
|
|
84
|
+
- **[Authentication](https://himanago.github.io/swallowkit/en/auth-guide)** - Auth and authorization
|
|
85
|
+
- **[Connectors](https://himanago.github.io/swallowkit/en/connector-guide)** - External data sources
|
|
88
86
|
|
|
89
|
-
|
|
90
|
-
// shared/models/category.ts
|
|
91
|
-
import { z } from 'zod';
|
|
87
|
+
## 🚀 Quick start
|
|
92
88
|
|
|
93
|
-
|
|
94
|
-
id: z.string(),
|
|
95
|
-
name: z.string().min(1).max(50),
|
|
96
|
-
createdAt: z.string().optional(),
|
|
97
|
-
updatedAt: z.string().optional(),
|
|
98
|
-
});
|
|
89
|
+
Create a new project:
|
|
99
90
|
|
|
100
|
-
|
|
91
|
+
```bash
|
|
92
|
+
npx swallowkit init my-app
|
|
93
|
+
cd my-app
|
|
101
94
|
```
|
|
102
95
|
|
|
103
|
-
|
|
96
|
+
Create a model and customize the schema:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
npx swallowkit create-model todo
|
|
100
|
+
```
|
|
104
101
|
|
|
105
102
|
```typescript
|
|
106
103
|
// shared/models/todo.ts
|
|
107
104
|
import { z } from 'zod';
|
|
108
|
-
import { category } from './category';
|
|
109
105
|
|
|
110
106
|
export const todo = z.object({
|
|
111
107
|
id: z.string(),
|
|
112
108
|
text: z.string().min(1).max(200),
|
|
113
109
|
completed: z.boolean().default(false),
|
|
114
|
-
category: category.optional(), // Nested object (not categoryId)
|
|
115
110
|
createdAt: z.string().optional(),
|
|
116
111
|
updatedAt: z.string().optional(),
|
|
117
112
|
});
|
|
@@ -119,288 +114,40 @@ export const todo = z.object({
|
|
|
119
114
|
export type Todo = z.infer<typeof todo>;
|
|
120
115
|
```
|
|
121
116
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
### 3. Generate CRUD Code
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
npx swallowkit scaffold shared/models/todo.ts
|
|
128
|
-
# or
|
|
129
|
-
pnpm dlx swallowkit scaffold shared/models/todo.ts
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
This auto-generates:
|
|
133
|
-
- ✅ Azure Functions (CRUD endpoints + Cosmos DB bindings)
|
|
134
|
-
- ✅ Next.js BFF API Routes (auto-validation + resource inference)
|
|
135
|
-
- ✅ React Components (type-safe forms)
|
|
136
|
-
|
|
137
|
-
If you selected `csharp` or `python` at `init` time, `swallowkit scaffold` also writes an OpenAPI document under `functions/openapi/` and generates native backend schema assets under `functions/generated/`.
|
|
138
|
-
|
|
139
|
-
### 4. Start Development Server
|
|
117
|
+
Generate CRUD code and start the dev server:
|
|
140
118
|
|
|
141
119
|
```bash
|
|
120
|
+
npx swallowkit scaffold todo
|
|
142
121
|
npx swallowkit dev
|
|
143
|
-
# or
|
|
144
|
-
pnpm dlx swallowkit dev
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
- Next.js: http://localhost:3000
|
|
148
|
-
- Azure Functions: http://localhost:7071
|
|
149
|
-
|
|
150
|
-
Backend-specific notes:
|
|
151
|
-
|
|
152
|
-
- **Python backends**: `swallowkit dev` uses **uv** for local runtime management. It installs or reuses a project-local `uv` binary under `.uv/bin`, keeps uv-managed Python under `.uv/python`, creates `functions/.venv` for the Functions app, and creates `functions/.codegen-venv` for Python schema generation.
|
|
153
|
-
- **C# backends**: Azure Functions isolated worker can take longer to answer on cold start while the worker build completes. `swallowkit dev` waits for the Functions host to start responding before it prints the backend URL as ready.
|
|
154
|
-
|
|
155
|
-
If you want to replace Cosmos DB Emulator data before startup, you can either generate an environment template or export the data currently stored in the local emulator:
|
|
156
|
-
|
|
157
|
-
```bash
|
|
158
|
-
npx swallowkit create-dev-seeds local
|
|
159
|
-
# edit dev-seeds/local/*.json
|
|
160
|
-
npx swallowkit dev --seed-env local
|
|
161
|
-
|
|
162
|
-
# or capture current emulator data as reusable seeds
|
|
163
|
-
npx swallowkit create-dev-seeds local --from-emulator --force
|
|
164
|
-
npx swallowkit dev --seed-env local
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
This workflow is designed for local debugging against the Cosmos DB Emulator:
|
|
168
|
-
|
|
169
|
-
- `create-dev-seeds <environment>` generates one JSON template per schema under `dev-seeds/<environment>/`
|
|
170
|
-
- `create-dev-seeds <environment> --from-emulator` exports the current data from the matching local Cosmos DB Emulator containers into the same file layout
|
|
171
|
-
- each file name maps to a schema/container, for example `shared/models/todo.ts` -> `dev-seeds/local/todo.json` -> `Todos`
|
|
172
|
-
- when you start `dev --seed-env <environment>`, SwallowKit replaces the existing data for each matching container with the JSON documents from that environment
|
|
173
|
-
- containers without a matching JSON file are left untouched
|
|
174
|
-
- if `--seed-env` is omitted, or `dev-seeds/<environment>/` does not exist, current emulator data is preserved
|
|
175
|
-
- exported files strip Cosmos system properties such as `_etag` before saving so they can be replayed safely
|
|
176
|
-
|
|
177
|
-
Why this is useful:
|
|
178
|
-
|
|
179
|
-
- preserve realistic local data that you registered manually while testing the app
|
|
180
|
-
- replay the same state for demos, onboarding sessions, and bug reproduction
|
|
181
|
-
- keep a schema-aligned seed snapshot without hand-copying documents out of the emulator
|
|
182
|
-
- quickly reset your emulator to a known-good state before validating behavior
|
|
183
|
-
|
|
184
|
-
Example file layout:
|
|
185
|
-
|
|
186
|
-
```text
|
|
187
|
-
dev-seeds/
|
|
188
|
-
local/
|
|
189
|
-
todo.json
|
|
190
|
-
category.json
|
|
191
|
-
staging-debug/
|
|
192
|
-
todo.json
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
Each `{schema}.json` file can contain either a single JSON object or an array of JSON objects. Every document must include an `id`:
|
|
196
|
-
|
|
197
|
-
```json
|
|
198
|
-
[
|
|
199
|
-
{
|
|
200
|
-
"id": "seed-todo-001",
|
|
201
|
-
"name": "Seed todo one",
|
|
202
|
-
"createdAt": "2026-03-21T00:00:00.000Z",
|
|
203
|
-
"updatedAt": "2026-03-21T00:00:00.000Z"
|
|
204
|
-
},
|
|
205
|
-
{
|
|
206
|
-
"id": "seed-todo-002",
|
|
207
|
-
"name": "Seed todo two",
|
|
208
|
-
"createdAt": "2026-03-21T00:00:01.000Z",
|
|
209
|
-
"updatedAt": "2026-03-21T00:00:01.000Z"
|
|
210
|
-
}
|
|
211
|
-
]
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
Recommended workflow:
|
|
215
|
-
|
|
216
|
-
```bash
|
|
217
|
-
npx swallowkit create-model todo
|
|
218
|
-
npx swallowkit scaffold shared/models/todo.ts
|
|
219
|
-
npx swallowkit create-dev-seeds local
|
|
220
|
-
# edit dev-seeds/local/todo.json
|
|
221
|
-
npx swallowkit dev --seed-env local
|
|
222
|
-
|
|
223
|
-
# or export your current local Cosmos Emulator data
|
|
224
|
-
npx swallowkit create-dev-seeds local --from-emulator --force
|
|
225
|
-
npx swallowkit dev --seed-env local
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
### 5. Use from Frontend
|
|
229
|
-
|
|
230
|
-
```typescript
|
|
231
|
-
import { api } from '@/lib/api/backend';
|
|
232
|
-
import type { Todo } from '@/shared/models/todo';
|
|
233
|
-
|
|
234
|
-
// Get all - call BFF endpoint
|
|
235
|
-
const todos = await api.get<Todo[]>('/api/todos');
|
|
236
|
-
|
|
237
|
-
// Create - validated by backend
|
|
238
|
-
const created = await api.post<Todo>('/api/todos', {
|
|
239
|
-
text: 'Buy milk',
|
|
240
|
-
completed: false
|
|
241
|
-
});
|
|
242
|
-
|
|
243
|
-
// Update - validated by backend
|
|
244
|
-
const updated = await api.put<Todo>('/api/todos/123', { completed: true });
|
|
245
|
-
|
|
246
|
-
// Delete
|
|
247
|
-
await api.delete('/api/todos/123');
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
### 6. Connect External Data Sources (Optional)
|
|
251
|
-
|
|
252
|
-
SwallowKit supports **connectors** for integrating external RDB databases and REST APIs alongside Cosmos DB, using the same Zod-driven workflow:
|
|
253
|
-
|
|
254
|
-
```bash
|
|
255
|
-
# Register a connector
|
|
256
|
-
npx swallowkit add-connector mysql --type rdb --provider mysql --connection-env MYSQL_CONNECTION_STRING
|
|
257
|
-
|
|
258
|
-
# Create a connector-aware model
|
|
259
|
-
npx swallowkit create-model user --connector mysql
|
|
260
|
-
# edit shared/models/user.ts (customize schema + connectorConfig)
|
|
261
|
-
|
|
262
|
-
# Scaffold generates connector-specific Functions code
|
|
263
|
-
npx swallowkit scaffold shared/models/user.ts
|
|
264
|
-
|
|
265
|
-
# Develop locally with mock data (no real MySQL needed)
|
|
266
|
-
npx swallowkit dev --mock-connectors
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
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.
|
|
270
|
-
|
|
271
|
-
## 🤖 AI / MCP Integration
|
|
272
|
-
|
|
273
|
-
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.
|
|
274
|
-
|
|
275
|
-
```bash
|
|
276
|
-
# Inspect framework-owned project metadata
|
|
277
|
-
npx swallowkit machine inspect project
|
|
278
|
-
|
|
279
|
-
# Validate SwallowKit conventions and generated artifacts
|
|
280
|
-
npx swallowkit machine validate project
|
|
281
|
-
|
|
282
|
-
# Generate through the official machine interface
|
|
283
|
-
npx swallowkit machine generate model todo --overwrite never
|
|
284
|
-
npx swallowkit machine generate scaffold todo --api-only
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
`swallowkit machine` is:
|
|
288
|
-
|
|
289
|
-
- non-interactive
|
|
290
|
-
- deterministic
|
|
291
|
-
- JSON-only on stdout
|
|
292
|
-
- structured on success and failure
|
|
293
|
-
|
|
294
|
-
For MCP clients, use the bundled stdio server:
|
|
295
|
-
|
|
296
|
-
```bash
|
|
297
|
-
npx swallowkit-mcp
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
Projects generated by `swallowkit init` include a project-scoped `.mcp.json` bootstrap that launches the locally installed SwallowKit MCP entrypoint. Agent runtimes that support repository MCP discovery can start using the same `swallowkit_*` tools automatically from the project root after project dependencies are installed.
|
|
301
|
-
|
|
302
|
-
When a runtime does not auto-load project MCP config, the generated instruction files still steer the agent toward `swallowkit machine ...`, and you can manually register the same launcher in the client.
|
|
303
|
-
|
|
304
|
-
The MCP server is intentionally a thin adapter with explicit tools only. It delegates real work to the machine CLI.
|
|
305
|
-
|
|
306
|
-
## 🏗️ Architecture
|
|
307
|
-
|
|
308
|
-
```
|
|
309
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
310
|
-
│ Frontend (React) │
|
|
311
|
-
│ - Client Components │
|
|
312
|
-
│ - Server Components (SSR) │
|
|
313
|
-
└──────────────────────────┬───────────────────────────────────┘
|
|
314
|
-
│ api.post('/api/todos', data)
|
|
315
|
-
▼
|
|
316
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
317
|
-
│ BFF Layer (Next.js API Routes) │
|
|
318
|
-
│ - Auto Schema Validation (Zod) │
|
|
319
|
-
│ - Error Handling │
|
|
320
|
-
└──────────────────────────┬───────────────────────────────────┘
|
|
321
|
-
│ HTTP Request
|
|
322
|
-
▼
|
|
323
|
-
┌─────────────────────────────────────────────────────────────┐
|
|
324
|
-
│ Azure Functions (Backend) │
|
|
325
|
-
│ - HTTP Triggers (CRUD) │
|
|
326
|
-
│ - Zod Validation (Re-check) │
|
|
327
|
-
│ - Business Logic │
|
|
328
|
-
│ - Data Source Bindings │
|
|
329
|
-
└──────────┬───────────────┼───────────────┬──────────────────┘
|
|
330
|
-
│ │ │
|
|
331
|
-
▼ ▼ ▼
|
|
332
|
-
┌────────────────┐ ┌──────────────┐ ┌──────────────────┐
|
|
333
|
-
│ Azure Cosmos │ │ External │ │ External SaaS │
|
|
334
|
-
│ DB (Default) │ │ RDB (MySQL │ │ APIs (REST) │
|
|
335
|
-
│ │ │ PostgreSQL) │ │ │
|
|
336
|
-
└────────────────┘ └──────────────┘ └──────────────────┘
|
|
337
122
|
```
|
|
338
123
|
|
|
339
|
-
|
|
340
|
-
- **BFF (Backend For Frontend)**: Next.js API Routes proxy to Azure Functions
|
|
341
|
-
- **Shared Schemas**: Zod schemas stay in `shared/models/` as the source of truth
|
|
342
|
-
- **OpenAPI Export for C#/Python**: Non-TypeScript Functions consume native-generated assets under `functions/generated/`
|
|
343
|
-
- **External Connectors**: MySQL, PostgreSQL, REST APIs — scaffold-generated Functions with the same BFF pattern
|
|
344
|
-
- **Contract Safety**: BFF and backend stay aligned through shared Zod or generated backend models
|
|
345
|
-
- **Managed Identity**: Secure service connections (no connection strings)
|
|
346
|
-
|
|
347
|
-
## 📦 Prerequisites
|
|
348
|
-
|
|
349
|
-
- Node.js 22.x
|
|
350
|
-
- **pnpm** (recommended): `corepack enable` or `npm install -g pnpm`
|
|
351
|
-
- npm also works — SwallowKit auto-detects the package manager (if pnpm is installed, it is always preferred)
|
|
352
|
-
- Azure CLI (`az`) for provisioning and deployment
|
|
353
|
-
- Azure Functions Core Tools 4.x for local Azure Functions development
|
|
354
|
-
- Azure Cosmos DB Emulator (local development)
|
|
355
|
-
- [Official documentation (vNext recommended)](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux)
|
|
356
|
-
- Windows: [Download](https://aka.ms/cosmosdb-emulator)
|
|
357
|
-
- Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
|
|
124
|
+
This generates Azure Functions, Next.js BFF routes, and React UI components — all typed from the shared schema.
|
|
358
125
|
|
|
359
|
-
|
|
126
|
+
## 🤖 AI-agent-friendly development
|
|
360
127
|
|
|
361
|
-
-
|
|
362
|
-
- Python backend: uv is used for local environment management
|
|
363
|
-
- C# backend: .NET 10 SDK and Azure Functions Core Tools 4.6.0 or later
|
|
128
|
+
SwallowKit provides machine-readable project metadata and command interfaces so coding agents can inspect the project structure, generate code through official commands, and validate changes without directly rewriting unrelated files.
|
|
364
129
|
|
|
365
|
-
|
|
130
|
+
The goal is to make AI-assisted development safer by giving agents explicit architectural boundaries.
|
|
366
131
|
|
|
367
|
-
##
|
|
132
|
+
## 📦 Generated project structure
|
|
368
133
|
|
|
369
|
-
Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations.
|
|
370
|
-
|
|
371
|
-
**1. Provision resources (Bicep IaC)**
|
|
372
|
-
|
|
373
|
-
```bash
|
|
374
|
-
npx swallowkit provision --resource-group my-app-rg
|
|
375
|
-
# or
|
|
376
|
-
pnpm dlx swallowkit provision --resource-group my-app-rg
|
|
377
134
|
```
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
135
|
+
.
|
|
136
|
+
├── app/ # Next.js pages and BFF API routes
|
|
137
|
+
├── shared/
|
|
138
|
+
│ └── models/ # Shared Zod schemas (source of truth)
|
|
139
|
+
├── functions/ # Azure Functions backend
|
|
140
|
+
├── infra/ # Bicep templates
|
|
141
|
+
├── lib/ # BFF helpers and scaffold config
|
|
142
|
+
└── .swallowkit/ # SwallowKit project metadata
|
|
385
143
|
```
|
|
386
144
|
|
|
387
|
-
|
|
145
|
+
## 🔗 Status
|
|
388
146
|
|
|
389
|
-
|
|
147
|
+
SwallowKit is under active development. The API, project structure, and generated output may change.
|
|
390
148
|
|
|
391
|
-
|
|
149
|
+
Feedback, issues, and small example use cases are welcome.
|
|
392
150
|
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
## License
|
|
151
|
+
## 📄 License
|
|
396
152
|
|
|
397
153
|
MIT
|
|
398
|
-
|
|
399
|
-
## 🔗 Related Links
|
|
400
|
-
|
|
401
|
-
- [SwallowKit VS Code Extension](https://marketplace.visualstudio.com/items?itemName=himanago.swallowkit-vscode)
|
|
402
|
-
- [Azure Static Web Apps](https://learn.microsoft.com/en-us/azure/static-web-apps/)
|
|
403
|
-
- [Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/)
|
|
404
|
-
- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/)
|
|
405
|
-
- [Next.js](https://nextjs.org/)
|
|
406
|
-
- [Zod](https://zod.dev/)
|
|
@@ -31,6 +31,13 @@ export declare function buildSharedTsConfig(): {
|
|
|
31
31
|
exclude: string[];
|
|
32
32
|
};
|
|
33
33
|
export declare function initCommand(options: InitOptions): Promise<void>;
|
|
34
|
+
/**
|
|
35
|
+
* Parse pnpm's `Ignored build scripts: foo@1.0.0, bar@2.0.0` warning and return
|
|
36
|
+
* the bare package names (without versions), de-duplicated.
|
|
37
|
+
*
|
|
38
|
+
* Matches both `ERR_PNPM_IGNORED_BUILDS` and the plain `Ignored build scripts:` line.
|
|
39
|
+
*/
|
|
40
|
+
export declare function parseIgnoredBuilds(output: string): string[];
|
|
34
41
|
export declare function injectSwallowKitNextConfig(nextConfigContent: string, projectName: string): string;
|
|
35
42
|
export declare function buildCSharpFunctionsProgramSource(): string;
|
|
36
43
|
export declare function buildCSharpFunctionsProjectSource(): string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAmB9C,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,KAAK,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAChD,KAAK,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAC9C,KAAK,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAyCtC,wBAAgB,mBAAmB;;;;;;;;;;;;;;;;;;EAoBlC;AAmFD,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,iBA8GrD;
|
|
1
|
+
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAmB9C,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,KAAK,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAChD,KAAK,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAC9C,KAAK,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAyCtC,wBAAgB,mBAAmB;;;;;;;;;;;;;;;;;;EAoBlC;AAmFD,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,iBA8GrD;AAwJD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAU3D;AAoDD,wBAAgB,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAKjG;AAED,wBAAgB,iCAAiC,IAAI,MAAM,CAiB1D;AAED,wBAAgB,iCAAiC,IAAI,MAAM,CA0B1D;AAED,wBAAgB,2BAA2B,CAAC,eAAe,EAAE,eAAe,GAAG,MAAM,CAcpF;AAED,wBAAgB,iCAAiC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM7F;AAyBD,wBAAgB,oCAAoC,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK7E;AAED,wBAAgB,qCAAqC,IAAI,MAAM,CAe9D"}
|