StackSnap is an AI-powered CLI tool that reads predefined scene definitions (YAML files describing full-stack features like authentication or user profiles), uses an OpenAI-compatible API to generate backend models, services, API routes, frontend pages, components, hooks, and TypeScript types, then safely injects the generated code into your existing project with automatic Git branching and rollback on failure.
graph LR
A["stacksnap add<br/>email-auth"] --> B["Read YAML<br/>Scene"]
B --> C["Create Git<br/>Branch"]
C --> D["AI Generates<br/>10 Batches"]
D --> E["Smart Inject<br/>& Dedup"]
E --> F["Install Deps<br/>& Commit"]
F --> G["Done!"]
D -.->|on failure| H["Auto<br/>Rollback"]
H -.-> C
style A fill:#00E0FF,stroke:#00B8D4,color:#000
style G fill:#4CAF50,stroke:#388E3C,color:#fff
style H fill:#FF5252,stroke:#D32F2F,color:#fff
$ stacksnap add email-auth
Using scene: email-auth
Created branch: stacksnap/email-auth
- Generating code with AI... (10 batches)
- Generated 12 file(s)
- Injecting files...
Created: src/services/authService.js, src/routes/auth.js, ...
Modified: prisma/schema.prisma, src/routes/index.js, ...
- Installing dependencies...
bcryptjs, jsonwebtoken, nodemailer, zod
- Changes committed.
Scene "email-auth" added successfully!npm install -g git+https://github.com/Sfrui/stacksnap.gitOr use directly:
npx --yes git+https://github.com/Sfrui/stacksnap.git initStackSnap supports any OpenAI-compatible API:
# OpenAI
export OPENAI_API_KEY="sk-your-key"
# Custom provider (e.g. DeepSeek, SiliconFlow, etc.)
export OPENAI_API_KEY="your-key"
export OPENAI_BASE_URL="https://your-api-endpoint/v1"
export OPENAI_MODEL="your-model-name"On Windows PowerShell:
$env:OPENAI_API_KEY="your-key"
# Detect project config (framework, ORM, package manager)
stacksnap init
# Add a full-stack scene (interactive selection)
stacksnap add
# Add a specific scene directly
stacksnap add email-authstacksnap init stacksnap add email-auth
| |
v v
Detect project Load scene YAML
framework, ORM, + check dependencies
package manager |
| v
v Create Git branch
.stacksnap.json stacksnap/email-auth
|
v
AI generates code in 10 batches
(models, index, services, routes,
API modules, types, pages, hooks,
components, router registration)
|
v
User confirms file list
|
v
Smart file injection
(new files, deduplication, merge)
|
v
Install dependencies
Git commit
|
(auto-rollback on failure)
When you run stacksnap add, StackSnap executes a 10-batch sequential generation pipeline:
| Batch | Output | Description |
|---|---|---|
| 1 | Backend Models | Prisma schema models, Sequelize model files, Drizzle table definitions, or JPA @Entity / MyBatis mapper XML |
| 2 | Model Index | Multi-file ORM index registration (Sequelize/Drizzle; skipped for Prisma, JPA, MyBatis) |
| 3 | Backend Services | Service layer with business logic (Express functions or Spring @Service classes) |
| 4 | Backend Routes | API route handlers + route registration (Express Router or Spring @RestController) |
| 5 | Frontend API | Frontend API request modules (skipped for Next.js) |
| 6 | Type Definitions | TypeScript interfaces and types |
| 7 | Frontend Pages | Vue 3 SFCs / React components / Next.js pages |
| 8 | Frontend Hooks | Composables / custom hooks |
| 9 | Frontend Components | Reusable UI components |
| 10 | Router Registration | Frontend route configuration (skipped for Next.js) |
Each batch uses AI prompts that include:
- Role-specific instructions (e.g. "You are a Prisma schema expert")
- Reference files from your project (for code style matching)
- Previously generated code from earlier batches (for consistency)
- Existing StackSnap code (to avoid duplicates across multiple scene additions)
|
Full email-based authentication system:
|
User profile management:
|
|
Role-based access control:
|
File upload and management:
|
|
In-app notification system:
|
More scenes coming soon... Have an idea? Open an issue or submit a PR! |
graph TD
EA[email-auth] --> UP[user-profile]
EA --> RBAC[rbac]
EA --> NOTIF[notification]
FU[file-upload]
style EA fill:#00E0FF,stroke:#00B8D4,color:#000
style UP fill:#7C4DFF,stroke:#651FFF,color:#fff
style RBAC fill:#FF6D00,stroke:#E65100,color:#fff
style NOTIF fill:#00C853,stroke:#00A844,color:#fff
style FU fill:#FF4081,stroke:#F50057,color:#fff
| Framework | ORM | Package Manager |
|---|---|---|
| Next.js (App Router) | Prisma | npm |
| Express + React (Ant Design) | Drizzle | yarn |
| Express + Vue 3 (Element Plus) | Sequelize | pnpm |
| Spring Boot + Vue 3 (Element Plus) | JPA (Hibernate) | Maven |
| Spring Boot + Vue 3 (Element Plus) | MyBatis | Gradle |
StackSnap doesn't just create files — it intelligently merges into your existing codebase:
| File Type | Strategy |
|---|---|
| New files | Created with proper directory structure |
| Prisma schemas | Model blocks injected after last }, wrapped in markers |
| Route index | Inserted after last router.use(), before module.exports |
| Model index | Inserted after last require(), before module.exports |
| Router index | Inserted after last path: entry, before closing ] |
| Service files | Deduplication by function name, only appends unique functions |
| Route files | Deduplication by HTTP method + path |
| JPA entities | Separate .java files, skipped if class name already exists |
| Spring services | @Service classes, deduplicated by class name |
| pom.xml | <dependency> blocks injected into <dependencies> section |
All modifications use @stacksnap added / @stacksnap end markers for traceability and multi-scene awareness.
stacksnap/
├── bin/
│ └── cli.ts # CLI entry point (commander)
├── src/
│ ├── commands/
│ │ ├── init.ts # Project detection & config generation
│ │ └── add.ts # Main scene injection workflow
│ ├── core/
│ │ ├── detector.ts # Framework/ORM/PM auto-detection
│ │ ├── detector-java.ts # Java/SpringBoot project detection
│ │ ├── scene-loader.ts # YAML scene file loading & caching
│ │ ├── code-generator.ts # AI API calls & multi-file output parsing
│ │ └── injector/
│ │ ├── file-injector.ts # Smart file create/modify with deduplication
│ │ ├── schema-injector.ts # Prisma schema model injection
│ │ ├── schema-injector-java.ts # Java entity/XML injection helpers
│ │ ├── dependency-installer.ts # npm/yarn/pnpm dependency installation
│ │ └── dependency-installer-java.ts # Maven/Gradle dependency installation
│ ├── adapters/ # Framework-specific adapters
│ │ ├── types.ts # Adapter interface definitions
│ │ ├── registry.ts # Adapter registry & lazy initialization
│ │ ├── locale.ts # i18n configuration (en-US default)
│ │ ├── utils.ts # Shared naming utilities
│ │ └── implementations/
│ │ ├── shared/
│ │ │ ├── backend.express.ts # Shared Express prompt builders
│ │ │ ├── express-backend.ts # Shared ExpressBackend class
│ │ │ ├── prisma-to-jpa.ts # Prisma → JPA type mapping
│ │ │ ├── prisma-to-mybatis.ts # Prisma → MyBatis type mapping
│ │ │ └── java-dependency-map.ts # npm → Maven dependency mapping
│ │ ├── express-vue/ # Express + Vue 3 adapter
│ │ ├── express-react/ # Express + React adapter
│ │ ├── nextjs/ # Next.js App Router adapter
│ │ └── springboot-vue/ # Spring Boot + Vue 3 adapter
│ │ ├── index.ts # Top-level adapter (id: 'springboot-vue')
│ │ ├── backend.ts # JPA/MyBatis backend adapter
│ │ ├── frontend.ts # Vue 3 frontend adapter (reuses express-vue)
│ │ ├── integration.ts # Page path resolution
│ │ └── prompts/
│ │ ├── backend.springboot.ts # SpringBoot prompt templates
│ │ └── frontend.vue.ts # Vue API module prompt (Spring variant)
│ ├── types/
│ │ └── index.ts # TypeScript interfaces
│ ├── utils/
│ │ └── git.ts # Git branch/commit/rollback operations
│ └── __tests__/ # Test suite (182 tests)
│ ├── adapters/
│ ├── injector/
│ └── utils/
├── scenes/ # Scene definitions (YAML)
│ ├── email-auth.yml
│ ├── user-profile.yml
│ ├── rbac.yml
│ ├── file-upload.yml
│ └── notification.yml
├── package.json
├── tsconfig.json
└── vitest.config.ts
Add a .yml file to scenes/:
name: my-feature
description: What this scene generates
version: 1.0.0
stackCompatibility:
- nextjs
- express-react
- express-vue
- springboot-vue
# Optional: declare scene dependencies
dependsOn:
- email-auth
dependencies:
- package: some-package
version: "^1.0.0"
entities:
- name: MyModel
fields:
id: String @id @default(uuid())
name: String
createdAt: DateTime @default(now())
api:
- method: GET
path: /api/my-endpoint
description: Returns my data
frontend:
pages:
- path: my-page
description: My page
components:
- path: MyComponent
description: My component
hooks:
- path: useMyHook
description: My hook
types:
- path: my-feature
description: MyModel types (MyModel, CreateMyModelInput)stacksnap init # Initialize project config (.stacksnap.json)
stacksnap add # Interactive scene selection
stacksnap add <scene-name> # Add specific scene directly
stacksnap --version # Show version
stacksnap --help # Show helpnpm install -g git+https://github.com/Sfrui/stacksnap.git# OpenAI
export OPENAI_API_KEY="sk-your-key"
# Custom provider (e.g. DeepSeek, SiliconFlow)
export OPENAI_API_KEY="your-key"
export OPENAI_BASE_URL="https://your-api-endpoint/v1"
export OPENAI_MODEL="your-model-name"cd your-project
stacksnap initThis detects your framework, ORM, TypeScript usage, directory structure, and package manager, then writes .stacksnap.json.
# Interactive — choose from the list
stacksnap add
# Direct — specify the scene name
stacksnap add email-authWhat happens automatically:
| Step | Action |
|---|---|
| 1 | Create Git branch stacksnap/<scene> |
| 2 | Check scene dependencies (warns if missing) |
| 3 | AI generates code in 10 batches |
| 4 | Show generated file list for confirmation |
| 5 | Inject files with smart merging and deduplication |
| 6 | Install required npm dependencies |
| 7 | Commit changes to Git |
| - | Auto-rollback if anything fails |
git checkout master
git merge stacksnap/email-authStackSnap also works with Spring Boot + Vue 3 projects. It auto-detects your Spring Boot project via pom.xml and generates Java backend code:
$ cd my-springboot-vue-project
$ stacksnap init
Detected: springboot-vue + jpa (Maven)
$ stacksnap add email-auth
Using scene: email-auth
Created branch: stacksnap/email-auth
- Generating code with AI... (10 batches)
- Generated 10 file(s)
- Injecting files...
Created: backend/src/main/java/com/example/app/entity/User.java,
backend/src/main/java/com/example/app/entity/VerificationToken.java,
backend/src/main/java/com/example/app/service/AuthService.java,
backend/src/main/java/com/example/app/controller/AuthController.java,
frontend/src/api/auth.js,
frontend/src/views/auth/LoginView.vue, ...
- Installing dependencies...
Added 5 dependency(ies) to pom.xml
- Changes committed.
Scene "email-auth" added successfully!The generated Spring Boot backend includes:
- JPA
@Entityclasses with proper annotations (@Id,@GeneratedValue,@Column) @Serviceclasses with repository injection and business logic@RestControllerclasses with@GetMapping/@PostMappingand@PreAuthorizefor RBAC- Maven dependencies automatically added to
pom.xml
npm install -g git+https://github.com/Sfrui/stacksnap.git| Variable | Required | Default | Description |
|---|---|---|---|
OPENAI_API_KEY |
Yes | — | API key for the AI provider |
OPENAI_BASE_URL |
No | https://api.openai.com/v1 |
Custom API endpoint |
OPENAI_MODEL |
No | gpt-4o-mini |
AI model to use |
| Category | Technology |
|---|---|
| Language | TypeScript 5.6 (strict mode, ES2020, CommonJS) |
| CLI Framework | commander 12.x |
| Interactive Prompts | inquirer 9.x |
| Terminal Styling | chalk 4.x, ora 5.x |
| AI Integration | openai 4.x SDK (OpenAI-compatible) |
| YAML Parsing | js-yaml 4.x |
| File Operations | fs-extra 11.x |
| Git Operations | simple-git 3.x |
| Testing | Vitest 4.x (182 tests) |
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Run tests (
npm test) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT