Cursor Rules Template: Rust + WASM + WebGL

Overview


This Cursor Rules configuration targets Rust + WASM + WebGL projects using Cursor AI. It defines how the AI should generate idiomatic Rust, leverage wasm-bindgen and web-sys for the browser, structure code and assets, and keep security and performance at the forefront while producing copyable, production-ready artifacts. It directly informs the .cursorrules configuration you paste at project root.


When to Use These Cursor Rules



- Starting a new in browser WebGL project compiled to WebAssembly with Rust.

- Sharing a standard approach for integrating wasm-bindgen glue with WebGL canvas rendering.

- Onboarding teammates with a consistent directory layout, linting, and testing workflows.

- Prototyping GPU shaders and asset pipelines with Cursor AI guidance.


Copyable .cursorrules Configuration


Copy and paste this at the root of your Rust + WASM + WebGL project. This is a .cursorrules configuration crafted for Cursor AI to produce consistent, safe, and testable code.


// Cursor Rules for Rust + WASM + WebGL (Cursor AI)
Framework Role & Context
Role: System
Context: You are Cursor AI configured to generate safe, idiomatic Rust + WebAssembly code with WebGL rendering. Avoid unsafe patterns, ensure portability, and provide testable glue layers.

Code Style and Style Guides
- Rust 1.70+ (edition 2021)
- Use wasm-bindgen, web-sys, js-sys
- Follow rustfmt and clippy guidelines; avoid excessive unsafe
- Document public items and export minimal, stable externs

Architecture & Directory Rules
- src/lib.rs as the entry point
- src/gl_context.rs for WebGL context creation
- src/render.rs for shader setup and draw calls
- shaders/ for vertex and fragment sources
- assets/ for textures and fonts
- static/index.html as host page
- tests/ for wasm-pack tests
- use wasm-pack and cargo as primary build tools

Authentication & Security Rules
- Do not embed secrets; fetch tokens via JS glue with strict origin checks
- Validate inputs at boundary before passing to Rust
- All network requests should flow through JS wrappers or the server

Database and ORM patterns
- No server-side DB calls from WASM. Use IndexedDB via web-sys or localStorage for client state
- Persist small, non-sensitive state via a stable key-value store; avoid large binary blobs in memory

Testing & Linting Workflows
- cargo test; wasm-pack test --chrome
- wasm-bindgen-test for browser environments
- CI: cargo test, cargo fmt -- --check, cargo clippy -- -D warnings

Prohibited Actions and Anti-patterns
- Do not manipulate the DOM directly from Rust; use JS glue
- Do not access Node.js primitives from WASM
- Do not bypass wasm-bindgen host bindings or stray into unsafe gaps without justification
- Do not rely on browser-specific quirks without validation across runtimes
Recommended Project Structure


project/
├─ Cargo.toml
├─ src/
│  ├─ lib.rs
│  ├─ gl_context.rs
│  ├─ render.rs
│  └─ utils.rs
├─ shaders/
│  ├─ vertex.glsl
│  └─ fragment.glsl
├─ static/
│  └─ index.html
├─ tests/
│  └─ integration_tests.rs

Core Engineering Principles



- Safety-first design; clear error handling and boundary checks between Rust and JS

- Thin glue layers; avoid leaking WASM memory to JS

- Deterministic builds; pin toolchain versions in Cargo.toml and npm if used

- Performance aware; minimize data copies in passes between JS and WASM

- Testability; provide unit tests in Rust and browser tests for GL paths


Code Construction Rules



- Export Rust functions to JS with wasm_bindgen

- Use web_sys for WebGL interactions

- Shaders management; embed or load at runtime

- Resource cleanup; drop GL resources properly

- Data interchange; use wasm_bindgen::JsCast and typed arrays

- CI and tests; ensure crates compile with features for wasm32-unknown-unknown

- Do not rely on unsafe unless necessary; keep unsafe blocks isolated and justified


Security and Production Rules



- Enable CSP and avoid inline scripts on production pages

- Never ship secrets in WASM; fetch tokens securely

- Guard against shader compilation failures; fail gracefully

- Memory budgets; limit heap growth

- Production builds should enable optimizations


Testing Checklist



- Unit tests for core Rust modules

- Browser tests for WebGL paths

- Integration tests to verify end-to-end rendering

- CI: run cargo test, wasm-pack test, lint checks


Common Mistakes to Avoid



- Directly manipulating the DOM from Rust without wrappers

- Leaking WebGL resources or failing to clean up GL state

- Not validating input prior to wasm calls

- Ignoring memory usage or relying on unsafe in production


FAQ


What is this Cursor Rules Template for Rust + WASM + WebGL?


This template provides a copyable .cursorrules configuration to help Cursor AI generate idiomatic Rust + wasm-bindgen + WebGL code, with a clear project structure, testing workflow, and security guidelines tailored for in-browser graphics work.


How do I apply the .cursorrules configuration to my project?


Copy the code block labeled Copyable .cursorrules Configuration and place it at the project root as .cursorrules. Cursor AI will use the rules to steer code generation, directory layout, and test scaffolding for Rust + WASM + WebGL workflows.


Which patterns are encouraged by this template?


The template encourages wasm-bindgen glue, web-sys usage for DOM/WebGL, shader management, safe memory handling, and explicit module boundaries between Rust and JS glue.


How should I run tests in CI for this stack?


CI should run cargo test (Rust), wasm-pack test for browser or headless environments, and lint checks (rustfmt and clippy). Include a simple WebGL render test to verify the pipeline ends in a renderable frame.


Can I adapt this template for other Rust + WASM stacks?


Yes. Update module names, shader paths, and asset locations, but keep the Cursor AI rules intact to maintain consistent architecture and testing workflows across variants.