Skip to content

v2: WIP Environment API#8260

Draft
thejackshelton wants to merge 32 commits intoQwikDev:build/v2from
thejackshelton:v2-env-api-gsd
Draft

v2: WIP Environment API#8260
thejackshelton wants to merge 32 commits intoQwikDev:build/v2from
thejackshelton:v2-env-api-gsd

Conversation

@thejackshelton
Copy link
Member

@thejackshelton thejackshelton commented Jan 24, 2026

What is it?

WIP Implementing the vite environment API. This is a WIP with the help of Opus 4.5. I will be cleaning up the artifacts created by claude code and grep mcp once the PR is in a better state. I am also playing around with GSD

  • Feature / enhancement
  • Bug
  • Docs / tests / types / typos
  • Infra

Description

Checklist

  • My code follows the developer guidelines of this project
  • I performed a self-review of my own code
  • I added a changeset with pnpm change
  • I made corresponding changes to the Qwik docs
  • I added new tests to cover the fix / functionality

thejackshelton and others added 28 commits January 22, 2026 23:34
- STACK.md - Technologies and dependencies
- ARCHITECTURE.md - System design and patterns
- STRUCTURE.md - Directory layout
- CONVENTIONS.md - Code style and patterns
- TESTING.md - Test structure
- INTEGRATIONS.md - External services
- CONCERNS.md - Technical debt and issues
Validation milestone for Qwik's Vite 7+ Environment API migration.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Mode: yolo
Depth: standard
Parallelization: enabled
Workflow agents: research=off, plan_check=on, verifier=on

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
12 requirements across 4 categories:
- Environment API Activation (3)
- Dev Mode with Environment API (4)
- Build Mode (3)
- Regression Testing (2)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phases:
1. Environment API Activation: ENV-01, ENV-02, ENV-03
2. Dev Mode Validation: DEV-01, DEV-02, DEV-03, DEV-04
3. Build Mode Validation: BUILD-01, BUILD-02, BUILD-03
4. Regression Testing: REG-01, REG-02

All v1 requirements mapped to phases.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 01: Environment API Activation
- Verification output approach documented
- Scope of checks defined (4 criteria + legacy fallback + manifest basic check)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 01: Environment API Activation
- 1 plan in 1 wave
- 1 parallel, 0 sequential
- Ready for execution
- ENV-01 verified: Vite 7+ detection via getViteMajorVersion()
- ENV-02 verified: environments.client/ssr config structure
- ENV-03 verified: this.environment usage in plugin hooks
- All 24 vite.unit.ts tests passing
- All 26 plugin.unit.ts tests passing
- Legacy fallback path for older Vite versions confirmed

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Tasks completed: 3/3
- Task 1: Run Environment API unit tests (24 tests pass)
- Task 2: Verify plugin hooks receive this.environment (26 tests pass)
- Task 3: Document verification results

SUMMARY: .planning/phases/01-environment-api-activation/01-01-SUMMARY.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 1 verified:
- ENV-01: Vite 7+ detected and environments config applied
- ENV-02: environments.client and environments.ssr exist
- ENV-03: this.environment available in plugin hooks

All 4/4 must-haves verified. Ready for Phase 2.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 02: Dev Mode Validation
- Implementation decisions documented
- Phase boundary established
Phase 02: Dev Mode Validation
- 2 plan(s) in 1 wave(s)
- 2 parallel, 0 sequential
- Ready for execution
- Added test verifying module invalidation with environment context
- Test confirms hotUpdate handler processes client environment modules
- Verifies full-reload sent through environment.hot.send()
- Proves per-environment HMR handling works correctly
- Documented DEV-03: hotUpdate hook verification with code evidence
- Documented DEV-04: environment.hot.send() verification with code evidence
- Documented per-environment module invalidation behavior
- Included code snippets from vite.ts and test evidence from vite.unit.ts
- All requirements verified with PASS status
Tasks completed: 3/3
- Verified existing hotUpdate tests pass
- Added module invalidation environment test
- Created verification report with evidence

SUMMARY: .planning/phases/02-dev-mode-validation/02-02-SUMMARY.md
- Verified dev server starts on port 3300
- Confirmed SSR environment generates q:container HTML (DEV-02)
- Confirmed client environment serves interactive bundles (DEV-01)
- Documented Environment API per-environment module graphs

VERIFICATION: .planning/phases/02-dev-mode-validation/02-01-VERIFICATION.md
Tasks completed: 3/3
- Task 1: Dev server started successfully on port 3300
- Task 2: Verified SSR and client rendering with per-environment module graphs
- Task 3: Created verification report with complete evidence

SUMMARY: .planning/phases/02-dev-mode-validation/02-01-SUMMARY.md
- DEV-01: Client renders using environments.client module graph ✓
- DEV-02: SSR renders using environments.ssr module graph ✓
- DEV-03: hotUpdate hook used (not legacy handleHotUpdate) ✓
- DEV-04: environment.hot.send() triggers full-reload ✓

Phase goal verified: Dev server correctly uses per-environment module graphs.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@changeset-bot
Copy link

changeset-bot bot commented Jan 24, 2026

⚠️ No Changeset found

Latest commit: ead1d9d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@thejackshelton thejackshelton changed the title V2 env api gsd v2: WIP Environment API Jan 24, 2026
thejackshelton and others added 2 commits January 24, 2026 12:27
Add curly braces to if statement in getViteMajorVersion function
to fix ESLint 'curly' rule violation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Quick task completed.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@github-actions
Copy link
Contributor

github-actions bot commented Jan 24, 2026

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name Status Preview Last Commit
qwik-docs ❌ Failed (View Log) ead1d9d

@pkg-pr-new
Copy link

pkg-pr-new bot commented Jan 24, 2026

Open in StackBlitz

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/core@8260
npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/router@8260
npm i https://pkg.pr.new/QwikDev/qwik/eslint-plugin-qwik@8260
npm i https://pkg.pr.new/QwikDev/qwik/create-qwik@8260

commit: ead1d9d

When a QRL segment is requested before its parent module has been
processed, the parent won't be in Vite's module graph yet. Previously
this caused "does not exist in the build graph" errors.

The fix:
1. Use environment's module graph directly when available (Vite 7+)
2. If parent not in graph, construct URL using /@fs/ prefix for
   absolute paths, allowing transformRequest to work directly
3. Handle virtual modules (like /virtual-qwik-devtools.ts) as-is

This ensures QRL parents can always be transformed regardless of
whether they've been added to the module graph yet.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@maiieul
Copy link
Member

maiieul commented Jan 28, 2026

Is it a good practice to commit all those agent .md files?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants