A CLI tool for creating and managing zkWasm applications
npm install zkwasm-dapp-cliA powerful scaffolding tool for zkWasm applications, similar to vue-cli and create-react-app, helping developers quickly create, manage, and deploy zkWasm applications.
| Feature | Description |
|---------|-------------|
| šÆ Quick Project Generation | Create new zkWasm projects from templates |
| š Smart Deployment Checks | Automatic deployment readiness validation with MD5 verification |
| āļø Environment Setup | Automatic development environment configuration |
| š¦ Multiple Templates | Support for Multiple project templates |
| š ļø Development Tools | Built-in build, test, and validation tools |
| š CI/CD Ready | Auto-generated GitHub Actions workflows |
| š Publish Management | Interactive publish script generation with error handling |
| Method | Command | Notes |
|--------|---------|-------|
| Global Install | npm install -g zkwasm-dapp-cli | Recommended |
| Local Install | npm install zkwasm-dapp-cli | Use with npx zkwasm-dapp |
| From Source | git clone && npm install && npm link | Development |
``bashCreate a basic Hello World project
zkwasm-dapp create my-zkwasm-app
$3
bash
cd my-zkwasm-app1. Initialize development environment
zkwasm-dapp init2. Install TypeScript dependencies and compile
cd ts
npm install
npx tsc
cd ..3. Validate project structure
zkwasm-dapp validate4. Build the application
zkwasm-dapp build5. Run locally (optional)
make run6. Generate and run publish script
zkwasm-dapp publish7. Check deployment readiness
zkwasm-dapp check --verbose
`$3
| Step | Command | Description |
|------|---------|-------------|
| 1. Setup |
| Initialize development environment |
| 2. Dependencies | cd ts && npm install && npx tsc && cd .. | Install and compile TypeScript |
| 3. Validate | zkwasm-dapp validate | Validate project structure |
| 4. Build | zkwasm-dapp build | Build zkWasm application |
| 5. Test | make run | Run local service for testing |
| 6. Publish | zkwasm-dapp publish | Generate/run publish script |
| 7. Deploy Check | zkwasm-dapp check | Verify deployment readiness |$3
For automated deployment to production platforms:
1. Switch to deployment branch:
`bash
git checkout -b zkwasm-deploy
`2. Enable GitHub Actions:
- Navigate to repository Settings ā Actions
- Enable GitHub Actions workflows
3. Configure Container Registry:
- Set up GitHub Container Registry (GCR) access
- Configure package settings for container images
- Ensure proper permissions for automated builds
4. Deploy:
bash
git push origin zkwasm-deploy
`The CI/CD pipeline will automatically build and containerize your zkWasm application on Github Container Registry. After successful GitHub Container Registry package build, you can deploy your application using the zkWasm deployment platform at https://deployment.zkwasmhub.com/.
š CLI Commands
| Command | Description | Usage Order |
|---------|-------------|-------------|
|
| Create new zkWasm project (Hello World template) | 1st |
| init | Initialize development environment and tools | 2nd |
| validate | Validate project structure and configuration | 3rd (after TS setup) |
| build | Build zkWasm application | 4th |
| publish | Generate/run publish script for zkWasm hub | 5th |
| check | Check deployment readiness | 6th (after publish) |$3
####
zkwasm-dapp create Creates a new zkWasm project with automatic setup:
| Option | Description | Default |
|--------|-------------|---------|
|
| Target directory | . |
| --skip-install | Skip automatic npm install and TypeScript compilation | false |Automatic Setup Process:
When you run
zkwasm-dapp create, the CLI automatically:
1. ā
Copies template files (Rust source, TypeScript service, configuration)
2. ā
Installs TypeScript dependencies (npm install in ts/ directory)
3. ā
Compiles TypeScript (npx tsc in ts/ directory)
4. ā
Initializes Git repository
5. ā
Sets up GitHub Actions (if selected)ā ļø Important for Development:
The CLI automatically handles initial setup, but during development you'll need to manually reinstall/recompile when:
- Adding new npm packages to
ts/package.json
- Modifying any files in ts/src/
- Updating TypeScript configurationbash
After adding dependencies or modifying TypeScript:
cd ts
npm install # Only needed when adding new dependencies
npx tsc # Needed after any TypeScript changes
cd ..
`When to use
:
- When you want to review package.json before installing dependencies
- In CI/CD environments where you control dependency installation
- When you prefer to install dependencies manually
- If you're experiencing network issues during project creationWith
--skip-install, you must manually run:
`bash
cd /ts && npm install && npx tsc && cd ..
`####
Initializes the development environment by:
- Checking for required tools (Rust, wasm-pack, wasm-opt, Node.js)
- Installing missing tools automatically
- Configuring project settings
- Creating development scripts
####
Validates project readiness by checking:
- Directory structure completeness
- Configuration file validity
- Dependency resolution
- TypeScript compilation status
####
Builds the complete application:
- Compiles Rust to WebAssembly
- Optimizes WASM with wasm-opt
- Generates TypeScript definitions
- Calculates MD5 hash for deployment tracking
- Copies artifacts to build directory
####
Checks deployment readiness by validating:
- Build artifacts (WASM file, TypeScript definitions)
- File integrity (MD5 hash calculation and verification)
- zkWasm hub connectivity (image existence check via API)
- Configuration files (Cargo.toml, package.json, tsconfig.json)
- Dependencies (Rust and Node.js dependency resolution)
- Environment (required tools availability)
####
Generates and manages publish scripts by:
- Creating customizable publish.sh scripts
- Supporting environment variables (ZKWASM_ADDRESS, ZKWASM_PRIVATE_KEY)
- Providing migration support (optional data import from existing images)
š Project Templates
$3
| Template | Use Case | Features |
|----------|----------|----------|
| Basic Hello World | Learning, getting started | ā¢ Basic Rust zkWasm module
ā¢ Simple TypeScript service
ā¢ State management example
ā¢ Settlement logic
ā¢ Standard build configuration |
$3
The CLI supports a modular template system. Currently, only the Basic Hello World template is available, but you can easily add more templates:
#### Template File Organization
The CLI uses a organized file structure for templates:
zkwasm-starter/
āāā common/ # Common files copied to all projects
ā āāā Dockerfile.ci # CI/CD Docker configuration
ā āāā Makefile # Build automation
ā āāā .gitignore # Git ignore rules
ā āāā .env.example # Environment variables template
ā āāā rust-toolchain # Rust toolchain specification
ā āāā .github/ # GitHub Actions workflows
ā āāā workflows/
āāā templates/ # Template-specific files
ā āāā basic/ # Basic Hello World template
ā āāā src/ # Rust source code
ā āāā ts/ # TypeScript service
ā āāā Cargo.toml.template
ā āāā README.md.template
āāā cli/ # CLI implementation
#### Adding New Templates
| Step | Action | Location |
|------|--------|----------|
| 1. Define Template | Add template config to
object | cli/create-project.js |
| 2. Create Template Files | Add template-specific source files | templates/ |
| 3. Add Template Logic | Implement template-specific generation | generateTemplatedFiles() function |
| 4. Update CLI | Add template option back to CLI | cli/index.js |#### Template Structure Example
`
templates/
āāā basic/ # Current Hello World template (uses src/)
āāā advanced/ # Future: Advanced features
ā āāā src/
ā āāā ts/
ā āāā config/
āāā defi/ # Future: DeFi-specific features
āāā src/
āāā ts/
āāā contracts/
#### Template Configuration
javascript
// In cli/create-project.js
const TEMPLATES = {
basic: {
name: 'Basic zkWasm Hello World',
description: 'Simple zkWasm application with basic functionality',
features: ['State management', 'Settlement logic']
},
// Add new templates here:
// advanced: { ... },
// defi: { ... }
};
`#### Template Project Structure
my-zkwasm-app/
āāā src/ # Rust source code
ā āāā lib.rs # Main entry point
ā āāā state.rs # State management
ā āāā config.rs # Configuration
āāā ts/ # TypeScript code
ā āāā src/ # TS source files
ā āāā package.json # TS dependencies
ā āāā tsconfig.json # TS configuration
āāā build-artifacts/ # Build outputs
āāā .github/ # GitHub Actions workflows (if enabled)
ā āāā workflows/
āāā Cargo.toml # Rust configuration (generated)
āāā Makefile # Build automation (from common/)
āāā Dockerfile.ci # CI/CD Docker configuration (from common/)
āāā .gitignore # Git ignore rules (from common/)
āāā .env.example # Environment variables template (from common/)
āāā rust-toolchain # Rust toolchain specification (from common/)
āāā zkwasm.config.json # zkWasm configuration (generated)
āāā README.md # Project documentation (generated)
File Sources:
- š Template-specific:
, ts/ directories from templates/basic/
- š Common files: , Dockerfile.ci, .gitignore, etc. from common/
- š Generated files: , README.md, zkwasm.config.json using Mustache templatesāļø Configuration (zkwasm-dapp init)
$3
| Environment | Optimize | Use Case | Build Command |
|-------------|----------|----------|---------------|
| Development |
false | Fast builds, debugging | cargo build --target wasm32-unknown-unknown |
| Production | true | Optimized builds | make build (includes wasm-opt) |
| Testing | false | Test features enabled | cargo build --target wasm32-unknown-unknown --features test |Note: The
zkwasm-dapp build command always performs production-level compilation and generates optimized WASM files, regardless of your environment configuration. For development and testing environments, use the generated scripts in the ./scripts/ directory:- Development/Testing builds: Use
./scripts/dev-build.sh for fast, unoptimized builds
- Production builds: Use zkwasm-dapp build or make build for optimized, deployment-ready WASMGenerate these scripts with
zkwasm-dapp init command.$3
`json
{
"environment": "development",
"build": {
"target": "wasm32-unknown-unknown",
"optimize": false,
"outputDir": "./build-artifacts"
},
"deployment": {
"autoCheck": true,
"environment": "development"
}
}
`š Deployment Checks (zkwasm-dapp check)
$3
| Category | Items | Status Indicators |
|----------|-------|-------------------|
| Build Artifacts | ā¢
ā¢ | ā
Found / ā Missing |
| WASM Integrity | ā¢ MD5 hash calculation
ā¢ File size validation
ā¢ Deployment history | ā
Valid / ā ļø Duplicate / ā Invalid |
| zkWasm Hub | ā¢ Image existence check
ā¢ API connectivity | ā
Available / ā Not found |
| Environment | ā¢ wasm-pack
ā¢ wasm-opt
ā¢ Node.js & npm | ā
Available / ā Missing |
| Configuration | ā¢ Cargo.toml
ā¢ package.json
ā¢ tsconfig.json | ā
Valid / ā Invalid |$3
`
š Starting deployment readiness check...Checking build artifacts...
ā
application_bg.wasm (45.2 KB)
ā
application_bg.wasm.d.ts (2.1 KB)
Checking WASM file integrity...
ā
WASM MD5: EA668FE59ADD59722F3B6FCCE828FD06
ā
WASM Size: 46.3 KB
Checking zkWasm hub...
ā
Image found on zkWasm hub
š Summary: ā
8 passed, ā ļø 0 warnings, ā 0 errors
š Publishing (zkwasm-dapp publish)
$3
| Parameter | Description | Default |
|-----------|-------------|---------|
|
| zkWasm hub API endpoint | https://rpc.zkwasmhub.com:8090 |
| path | WASM file path | node_modules/zkwasm-ts-server/src/application/application_bg.wasm |
| circuit_size | Circuit size parameter | 22 |
| address | User wallet address | From environment or prompt |
| priv | Private key | From environment or prompt |
| description | Image description | User input |
| creator_paid_proof | Creator pays for proofs | false |
| creator_only_add_prove_task | Restrict proof creation | false |
| auto_submit_network_ids | Auto-submit networks | Optional |
| import_data_image | Migration data source | Optional |$3
| Variable | Purpose |
|----------|---------|
|
ZKWASM_ADDRESS | Wallet address for publishing |
| ZKWASM_PRIVATE_KEY | Private key for signing |š ļø Development Tools
$3
| Script | Purpose | Location |
|--------|---------|----------|
|
dev-build.sh | Development builds | ./scripts/ (generated) |
| publish.sh | Publishing | ./ts/ (generated) |$3
| Tool | Purpose | Installation |
|------|---------|--------------|
| Rust | Core compilation |
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh |
| wasm-pack | WASM packaging | curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf \| sh |
| wasm-opt | WASM optimization | brew install binaryen (macOS)
sudo apt install binaryen (Ubuntu) |
| Node.js | TypeScript compilation | https://nodejs.org/ |š§ Troubleshooting
$3
| Issue | Symptoms | Solution |
|-------|----------|----------|
| Build Failure |
wasm-pack build fails | ā¢ Update Rust: rustup update
ā¢ Add target: |
| Dependency Error | npm install fails | ā¢ Clear cache: npm cache clean --force
ā¢ Remove node_modules and reinstall |
| Environment Issues | Tools not found | ā¢ Run
ā¢ Check PATH configuration |
| Check Failures | Deployment check errors | ā¢ Run
ā¢ Validate with | Platform | Notes |
|----------|-------|
| WSL | ā¢ Use Linux versions of tools
ā¢ Restart terminal after Rust installation |
| Windows | ā¢ Use WSL2 or Git Bash
ā¢ May require administrator privileges |
| macOS | ā¢ Use Homebrew for binaryen
ā¢ Ensure Xcode command line tools installed |
| Type | Description |
|------|-------------|
| Bug Reports | Use GitHub Issues with bug template |
| Feature Requests | Use GitHub Issues with feature template |
| Pull Requests | Fork ā Feature branch ā PR |
| Documentation | Improve README, add examples |
MIT License - see LICENSE file for details.
| Document | Description |
|----------|-------------|
| Template System | Template structure and customization |
| CLI Reference | Detailed command documentation |
| zkWasm Development Recipe | Official comprehensive guide |
---
Powered by Delphinus Lab š