High-performance fullstack React framework - Client package
npm install @zap-js/clientOfficial CLI and development tools for ZapJS - the fullstack Rust + React framework.
Install the ZapJS CLI globally to use the zap command anywhere:
``bash`
npm install -g @zapjs/client
After installation, verify it works:
`bash`
zap --version
zap --help
For project-specific installation:
`bash`
npm install --save-dev @zapjs/client
Then use via npm scripts in your package.json:
`json`
{
"scripts": {
"dev": "zap dev",
"build": "zap build",
"serve": "zap serve"
}
}
If you're contributing to ZapJS:
`bash`
cd packages/client
npm install
npm run build
npm link
This creates a global symlink for local testing. The zap command will now use your local development version.
Create a new ZapJS project with the specified template.
`bash`
zap new my-app
zap new my-app --template fullstack
zap new my-app --no-install --no-git
Options:
- -t, --template - Template to use: basic or fullstack (default: basic)--no-install
- - Skip npm install--no-git
- - Skip git initialization
Start the development server with hot reload for both Rust and TypeScript.
`bash`
zap dev
zap dev --port 3000 --vite-port 5173
zap dev --release --skip-build
Options:
- -p, --port - API server port (default: 3000)--vite-port
- - Vite dev server port (default: 5173)--no-open
- - Don't open browser automatically-l, --log-level
- - Log level: debug, info, warn, error (default: info)--release
- - Build Rust in release mode (slower build, faster runtime)--skip-build
- - Skip initial Rust build (use existing binary)--binary-path
- - Path to pre-built zap binary--codegen-binary-path
- - Path to pre-built zap-codegen binary
Keyboard Shortcuts (during dev):
- r - Manually trigger Rust rebuildc
- - Regenerate TypeScript bindingsq
- - Quit dev serverCtrl+C
- - Stop server
Build your application for production.
`bash`
zap build
zap build --output ./dist --target x86_64-unknown-linux-gnu
zap build --skip-frontend
Options:
- --release - Build optimized release (default: true)-o, --output
-
- Output directory (default: ./dist)
- --target - Cross-compile target (e.g., x86_64-unknown-linux-gnu)
- --skip-frontend - Skip Vite frontend build
- --skip-codegen - Skip TypeScript binding generationOutput Structure:
`
dist/
├── bin/
│ └── zap # Rust binary
├── static/ # Frontend assets (if built)
├── config.json # Production config
└── manifest.json # Build metadata
$3
Run the production server.
bash
zap serve
zap serve --port 8080 --host 0.0.0.0
zap serve --config ./custom-config.json
`Options:
-
- Server port
- --host - Host to bind to (default: 0.0.0.0)
- -c, --config - Path to config file
- -w, --workers - Number of worker threads$3
Generate TypeScript bindings from Rust exports.
`bash
zap codegen
zap codegen --output ./src/api
zap codegen --input ./metadata.json
`Options:
-
- Input metadata JSON file
- -o, --output - Output directory (default: ./src/api)$3
Scan routes directory and display/generate route tree.
`bash
zap routes
zap routes --routes-dir ./routes --output ./src/generated
zap routes --json
zap routes --verbose
`Options:
-
- Routes directory path
- -o, --output - Output directory for generated files
- --json - Output routes as JSON
- --verbose - Show full handler codeProject Structure
A typical ZapJS project structure:
`
my-app/
├── routes/ # File-based routing
│ ├── __root.tsx # Root layout
│ ├── index.tsx # Home page (/)
│ ├── about.tsx # About page (/about)
│ ├── posts/
│ │ ├── [id].tsx # Dynamic route (/posts/:id)
│ │ └── index.tsx # Posts index (/posts)
│ └── api/
│ ├── hello.ts # API route (/api/hello)
│ └── users.$id.ts # Dynamic API route (/api/users/:id)
├── server/
│ ├── src/
│ │ └── main.rs # Rust server entry point
│ └── Cargo.toml # Rust dependencies
├── src/
│ └── generated/ # Auto-generated files
│ ├── routes.tsx # Generated route tree
│ └── routeManifest.json
├── package.json
├── Cargo.toml # Workspace Cargo.toml
├── tsconfig.json
└── zap.config.ts # Optional config
Configuration
$3
typescript
import { defineConfig } from 'zap';export default defineConfig({
server: {
port: 3000,
hostname: '127.0.0.1',
},
dev: {
apiPort: 3000,
clientPort: 5173,
watchRust: true,
watchTypeScript: true,
open: true,
},
});
`Routing Conventions
$3
ZapJS uses Next.js-style file-based routing:
-
→ /
- → /about
- → /posts/:id
- → /posts/* (catch-all)
- routes/__root.tsx → Root layout wrapper
- routes/_layout.tsx → Layout wrapper$3
TypeScript files in
routes/api/ become API endpoints:`typescript
// routes/api/users.ts
export const GET = async () => {
return { users: [] };
};export const POST = async ({ request }: { request: Request }) => {
const body = await request.json();
return { created: body };
};
`Supported Methods:
, POST, PUT, DELETE, PATCH, HEAD, OPTIONS$3
Use
or $param syntax for dynamic segments:`typescript
// routes/api/users.$id.ts or routes/api/users/[id].ts
export const GET = async ({ params }: { params: { id: string } }) => {
return { id: params.id };
};
`Troubleshooting
$3
After installing globally, if
is not found:1. Check npm global bin directory is in PATH:
`bash
npm config get prefix
`2. Add npm global bin to your PATH:
bash
# Add to ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"
`3. Verify installation:
bash
which zap
zap --version
`$3
1. Ensure Rust is installed:
bash
rustc --version
cargo --version
`2. Clean and rebuild:
bash
cargo clean
npm run build
zap dev
`3. Check port availability:
bash
lsof -i :3000 # Check if port 3000 is in use
`$3
1. Ensure
binary exists:
`bash
cargo build --release --bin zap-codegen
`2. Manually run codegen:
bash
zap codegen
``- Documentation
- Examples
- Discord Community
- GitHub Issues
MIT