Issue Review: cloudflare/workers-sdk#7213

Summary

SvelteKit projects created via C3 with the "lucia" auth addon fail to build for Cloudflare due to incompatible @node-rs/argon2 native/WASM dependencies.

Findings

• Created: 2024-11-10
• Updated: 2025-10-30
• Version: create-cloudflare 2.32.0 → 2.62.3 (current)
• Component: C3 (create-cloudflare) / SvelteKit integration
• Labels: bug
• Comments: 0

Key Evidence

1. Root cause identified: The Svelte CLI (sv) lucia addon installs @node-rs/argon2 which uses native Node.js bindings (.node files) and WASM modules that are incompatible with Cloudflare Workers/Pages runtime.

2. Related issues confirm this is a known limitation:

   • SvelteKit #13061 (closed) - Same error, comments through Aug 2025 show ongoing issues
   • Lucia #1567 (closed) - Maintainer confirmed: "@node-rs/argon2 doesn't work in CF"
   • workers-sdk #6231 (closed) - Feature request for esbuild external support for same error

3. SvelteKit adapter fix (PR #13132, Dec 2024): Removed esbuild bundling step, but this doesn't solve the fundamental incompatibility - the runtime still cannot execute native bindings.

4. Lucia v3 deprecated (June 2025): The library this bug relates to has been deprecated, though the underlying issue with @node-rs/argon2 + Cloudflare remains.

5. No C3-specific fix exists: C3 delegates to sv (Svelte CLI) which offers lucia addon without Cloudflare compatibility warnings.

Recommendation

Status: KEEP OPEN

Reasoning: This is a legitimate documentation/UX issue. While the root cause is an upstream incompatibility (@node-rs/argon2 cannot run on Cloudflare), C3 should either:

1. Warn users when selecting lucia addon that it's incompatible with Cloudflare
2. Document the workaround (use alternative hashing libraries like bcryptjs or @oslojs/crypto)
3. Consider excluding incompatible addons from the sv CLI flow for Cloudflare projects

Action: Add documentation or warning about Cloudflare-incompatible Svelte CLI addons, particularly lucia.

Root Cause Analysis

The issue occurs in this flow:

1. User runs npx create-cloudflare --framework=svelte
2. C3 delegates to sv (Svelte CLI) via packages/create-cloudflare/src/frameworks/index.ts
3. User selects "lucia" addon in sv's interactive prompts
4. sv installs @node-rs/argon2 as a dependency (lucia requires it for password hashing)
5. Build fails because @node-rs/argon2 uses:
   • Native Node.js bindings (.node files)
   • WASM modules (@node-rs/argon2-wasm32-wasi)
   • Neither can be bundled/executed in Cloudflare's workerd runtime

Code path: packages/create-cloudflare/src/frameworks/index.ts:runFrameworkGenerator() - This function runs the framework CLI (sv) without any filtering of Cloudflare-incompatible options.

Proposed Solution

Option A (Minimal - Documentation):
Add a note to C3 docs and/or post-creation output warning about Cloudflare-incompatible Svelte addons.

Option B (Better - Runtime Warning):
After sv CLI completes, scan package.json for known incompatible packages and warn users:

// In packages/create-cloudflare/src/frameworks/svelte.ts or similar
const CLOUDFLARE_INCOMPATIBLE_PACKAGES = [
  '@node-rs/argon2',
  '@node-rs/bcrypt', 
  // other known incompatible packages
];

async function checkIncompatibleDependencies(projectPath: string) {
  const pkgJson = JSON.parse(await readFile(join(projectPath, 'package.json'), 'utf-8'));
  const allDeps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
  
  const incompatible = CLOUDFLARE_INCOMPATIBLE_PACKAGES.filter(pkg => pkg in allDeps);
  
  if (incompatible.length > 0) {
    warn(`The following packages are incompatible with Cloudflare Workers/Pages:`);
    incompatible.forEach(pkg => warn(`  - ${pkg}`));
    warn(`Consider using Cloudflare-compatible alternatives like bcryptjs or @oslojs/crypto`);
  }
}

Option C (Best - Upstream coordination):
Work with SvelteKit team to add Cloudflare-specific addon filtering when sv detects it's being run in a Cloudflare context.

Implementation Difficulty

Medium

Justification:

• Option A (docs) is trivial
• Option B requires adding post-scaffold validation logic, understanding the package.json structure after sv runs, and maintaining a list of incompatible packages
• Option C requires cross-project coordination

Files to Modify

1. packages/create-cloudflare/src/frameworks/index.ts - Add post-scaffold compatibility check
2. packages/create-cloudflare/src/frameworks/package.json - Potentially add new dependencies for scanning
3. Documentation files (if taking docs-only approach)

Testing Recommendations

1. Manual testing: Run npx create-cloudflare --framework=svelte, select lucia addon, verify warning appears
2. Unit tests: Add tests for incompatible package detection logic
3. E2E tests: Verify the warning appears in the C3 output when incompatible packages are detected

Workarounds for Users

Users encountering this issue can:

1. Don't select "lucia" addon during sv setup when targeting Cloudflare
2. Use bcryptjs or @oslojs/crypto instead of @node-rs/argon2
3. Use the argonia package (WASM-based argon2 for Workers, though has some limitations)
4. Implement custom hashing using Web Crypto API (scrypt)

Suggested Comment

This issue is caused by the @node-rs/argon2 package (installed by the lucia addon) using native Node.js bindings that are incompatible with Cloudflare Workers/Pages runtime.

Workaround: When using C3 with SvelteKit for Cloudflare deployment, avoid selecting the "lucia" addon. Instead, use Cloudflare-compatible alternatives for password hashing:

• bcryptjs (pure JS)
• @oslojs/crypto (pure JS)
• argonia (WASM-based, works on Workers but has some Pages limitations)

We're keeping this open to track adding a warning or documentation about Cloudflare-incompatible Svelte CLI addons.