docs: add WASM plugin debugging section to CONTRIBUTING.md

[staging-devin-ai-integration]

Summary

Adds a new "Debugging the WASM plugin" section to CONTRIBUTING.md covering:

• Adding debug output — how to use println!(), eprintln!(), and dbg!() in the Rust visitor code, and why they work (WASI target vs wasm32-unknown-unknown).
• Viewing logs during tests — using cargo test -- --nocapture and the caveat that #[plugin_transform] is not invoked by the test!() macro.
• Viewing logs at build time — how WASI stderr surfaces in the terminal when running inside Next.js or another SWC-based bundler, with the rebuild command.
• Where to find snapshot test output — location of the __swc_snapshots__ directory and how to update snapshots with UPDATE=1 cargo test.

Review & Testing Checklist for Human

• Verify the debugging instructions are accurate for your local setup (e.g. cargo test -- --nocapture shows output as described)
• Confirm the snapshot path packages/typewind/tests/__swc_snapshots__/swc/lib.rs/ is correct

Notes

Documentation-only change — no code changes.

Link to Devin session: https://staging.itsdev.in/sessions/1673ddc0f2804c9e8c973b134923910c
Requested by: @Mokshit06

[staging-devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
typewind	Error		Apr 8, 2026 3:31am

[staging-devin-ai-integration]

Code Review: PR #72 — Add WASM Plugin Debugging Section to CONTRIBUTING.md

Overall Assessment

Documentation-only change. The content is useful and fills a real gap in the contributing guide. A few accuracy and completeness issues below.

---

🟡 Accuracy / Edge Cases

1. cargo build-wasi is a custom alias, not a standard cargo command — should be clarified

The docs suggest:

cd packages/typewind
cargo build-wasi --release && cp target/wasm32-wasip1/release/typewind_swc.wasm dist

cargo build-wasi is a custom alias defined in .cargo/config.toml, not a standard cargo subcommand. New contributors unfamiliar with the project might be confused. Add a note like:

build-wasi is a cargo alias defined in packages/typewind/.cargo/config.toml. See it for the exact flags used.

2. Snapshot path is correct ✓

The documented path packages/typewind/tests/__swc_snapshots__/swc/lib.rs/ matches the actual repo structure — the snapshot file boo.js lives at packages/typewind/tests/__swc_snapshots__/swc/lib.rs/boo.js.

3. println!() / eprintln!() claim needs a caveat for WASI runtime differences

The docs state these macros "are fully functional" because of the WASI target. This is true when running under cargo test (native) or a WASI-compliant runtime, but when the WASM plugin runs inside SWC's WASM runner in Next.js, the stderr/stdout routing depends on the host's WASI implementation. Some bundler versions may buffer or discard these outputs. A note mentioning this possibility would save contributors debugging time.

4. Missing mention of --target wasm32-wasip1 for cargo test

The docs say to run cargo test -- --nocapture, but this runs tests for the host target (native). The SWC plugin is compiled for wasm32-wasip1. The test!() macro in lib.rs works natively because it tests the visitor logic directly (as the docs correctly note), but this subtlety deserves a brief mention — contributors might wonder why cargo test works without specifying the WASM target.

---

🟢 Minor / Nits

5. Grammatical issue in existing text (pre-existing)

The existing line above the new section says:

"You can run update the test suite snapshot"

Should be: "You can update the test suite snapshot"

Since this PR is touching CONTRIBUTING.md, it would be a good opportunity to fix this typo at line 23.

6. Consider adding a "Common pitfalls" subsection

A brief mention of common issues would be helpful:

• Forgetting to rebuild the WASM after Rust changes
• The WASM binary in dist/ being stale vs. the Rust source
• cargo test passing but the WASM build failing (e.g., due to WASI-incompatible dependencies)

---

Summary

Good documentation addition. The content is accurate for the common case. Adding clarifications about the custom cargo alias and WASI runtime variability would make it more robust for new contributors.