HarperFast / HarperFast/harper-pro
Frameworks: add Next.js hosting integration test suite
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 0
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 80
Description
## Context
Harper hosts Next.js applications via `@harperfast/nextjs` in production, but there is zero integration test coverage for this path in `harper-pro` today. Two production deployment patterns drive the requirements:
- **Composable web (e-commerce)**: Next.js front end backed by Harper tables, ISR + `use cache` directives writing through to a `nextjs_isr_cache` table, EAV-style catalog tables with 30M+ rows feeding product pages.
- **Multi-brand platform with runtime secrets injection**: secrets pulled from an external vault by a Harper component at startup, then exposed to the Next.js process before it boots. No application tables in this variant — a single ISR `HttpCache` table is the only persistence. Workers run at 60–80% utilization sustained.
A dedicated QA cluster — `hdb-frameworkhosting-qa` — already exists for this surface.
## Existing coverage
None in `harper-pro`. A repo-wide search for `next.js`/`nextjs`/`framework` across `integrationTests/`, `smokeTests/`, and `stressTests/` returns only unrelated component fixtures (`smokeTests/.components/early-hints/`, `smokeTests/.components/acl-connect-example/`). No `frameworks/` directory, no Next.js fixture, no `@harperfast/nextjs` references in tests.
## Gaps to fill
### NF-a: Deploy + serve baseline
Deploy a Next.js standalone build as a Harper component; assert the app process starts, the Harper HTTP server fronts it, and a request to a static route returns 200 with rendered HTML.
### NF-b: ISR + `use cache` backed by Harper tables
- Configure a `nextjs_isr_cache` table and verify ISR writes/reads flow through it (rows present after first render; subsequent requests served from cache).
- Verify the `use cache` directive writes to a Harper table and reads hit Harper on warm requests.
### NF-c: Cache invalidation + TTL
- Tag-based invalidation: tag a cache entry, call the invalidation API, assert the next request re-renders.
- TTL enforcement: write a cache entry with a TTL, wait past expiry, assert the entry is treated as stale and re-rendered.
### NF-d: Harper REST API on the same port
With the Next.js app deployed, assert the Harper REST API (`/`-rooted operations endpoint or equivalent table REST) is reachable on the same listening port as the Next.js app, without a separate listener.
### NF-e: Schema-only component co-deployed with Next.js + production build
Deploy a schema-only Harper component (no resources) alongside the Next.js component, build with `cacheMaxMemorySize: 0`, and assert: schema applies, Next.js boots, requests still serve correctly under the zero-memory cache constraint.
### NF-f: Startup secrets injection
A Harper component reads secrets from an external source (mock vault/file) before the Next.js process is started; assert the secrets are present as environment variables inside the Next.js runtime context (e.g. via a test page that echoes a non-secret marker derived from the injected value).
## Implementation notes
- Target environment: the `hdb-frameworkhosting-qa` cluster for any cluster-level variants; single-node test fixtures suffice for NF-a through NF-e.
- New top-level directory `integrationTests/frameworks/` is appropriate — there is no existing home for this surface. Align with the fixture-directory + `setupHarperWithFixture` convention per [HarperFast/harper#1215](https://github.com/HarperFast/harper/issues/1215): each test gets a real component fixture directory (`integrationTests/frameworks/fixture-nextjs-*/`) rather than inline component definitions, and uses `setupHarperWithFixture` from `@harperfast/integration-testing`.
- A Next.js fixture will need its own `package.json` and a built `.next/standalone/` output committed or built in CI. Decide upfront whether to vendor a minimal app or build in a setup hook — vendoring is faster but couples the test to a Next.js version.
- The mock vault for NF-f can be a local JSON file read by a small Harper component; no external dependency required.
## Priority
P3
Contributor guide
Assessment
This issue has not been assessed yet.