Contributing

This page covers local setup, checks, and the boundaries to keep in mind when changing SimDeck.

Setup

Requirements:

• macOS with Xcode and iOS Simulator runtimes.
• Node.js 18 or newer.
• Rust stable.
• x264 (brew install x264).
• Optional Android SDK tools for Android emulator work.

git clone https://github.com/NativeScript/SimDeck.git
cd SimDeck
npm install
npm run build

Run the built CLI:

./build/simdeck

Run the development server:

npm run dev

The server log is written to build/cli.log.

Repository map

Folder	Purpose
packages/server/	CLI entrypoint, service, API, stream transport, metrics
packages/server/native/	macOS simulator bridge
packages/client/	Browser UI
packages/	Inspectors, VS Code extension, and simdeck/test
scripts/	Build, package, and test helpers
docs/	VitePress documentation

Working rules

• Keep simulator-native logic in packages/server/native/.
• Keep server behavior in packages/server/.
• Keep browser presentation in packages/client/.
• Keep runtime inspector logic in the matching packages/*-inspector package.
• Prefer a stable CLI command or API route over hidden environment behavior.
• Update docs when changing CLI flags, API routes, stream behavior, or inspector methods.

Build and check

npm run format
npm run lint
npm run test
npm run ci

What npm run ci covers:

1. Formatting and lint checks.
2. Full build.
3. Rust and client tests.
4. VS Code extension package.

Integration tests

iOS:

npm run build:cli
npm run build:client
npm run test:integration:cli

Verbose iOS run:

npm run test:integration:cli:verbose

Android:

npm run build:cli
npm run build:simdeck-test
npm run test:integration:android

Useful variables:

Variable	Purpose
SIMDECK_INTEGRATION_VERBOSE=1	Print more detail
SIMDECK_INTEGRATION_SHOW_SIMULATOR=1	Show Simulator.app during tests
SIMDECK_INTEGRATION_KEEP_SIMULATOR=1	Keep temporary iOS simulator
SIMDECK_INTEGRATION_ANDROID_AVD=<name>	Pick an Android AVD
SIMDECK_INTEGRATION_BOOT_ANDROID=1	Boot Android locally

Docs

npm run docs:dev
npm run docs:build

The docs site lives under docs/ and deploys to GitHub Pages from .github/workflows/docs.yml.

Issues and PRs

For simulator or stream bugs, include:

• Reproduction steps.
• simdeck --version.
• macOS and Xcode versions.
• Foreground service output or build/cli.log.
• Any relevant screenshots or CLI output.

License

SimDeck is licensed under Apache-2.0. Contributions are licensed under the same terms.