HarperFast / HarperFast/nextjs

Turbopack build can't resolve `import 'harper'` (Next 16); README recommends an import that breaks the build

Open
#51 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
4
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Summary

On Next.js 16, a top-level `import 'harper'` in server code fails the plugin's on-startup build with:

```
Error: Turbopack build failed with 1 errors:
Module not found: Can't resolve 'harper'
> import 'harper';
```

`withHarper()` externalizes `harper` for the **webpack** path and adds it to `serverExternalPackages`, but adds nothing for Turbopack (`src/withHarper.cts` L31–43; the comment at L24–26 notes Turbopack support is "currently proving difficult"). Since v16 defaults to Turbopack (`src/plugin.ts` L196–197), the build throws, and the plugin logs the error and `return`s **without serving** (`src/plugin.ts` L254–264) — so the app boots but every route 404s. It's a silent failure that's especially confusing on remote/Studio deploys (the component "deploys" but serves nothing).

## Interaction with #37

Forcing `bundler: webpack` gets past module resolution, but then hits #37: the same top-level `import 'harper'` opens the database during Next's build-time page-data collection → `IO error: While lock file: .../database/data/LOCK: Resource temporarily unavailable`. So a top-level `import 'harper'` breaks the build under **both** bundlers, for two different reasons (resolution under Turbopack, DB lock under webpack).

## The docs recommend the import that breaks it

README step 5 (~L63–75) tells users to `import 'harper'` in server-side code. That guidance triggers this on v16. Notably, the plugin's **own** `next-16` fixture doesn't import `harper` in Next code — it keeps Harper access in a `jsResource` (`fixtures/next-16/greeting.js`) and the Next pages use the injected `tables` global / `process.env`. Using the injected `tables` global directly (no top-level import) builds and serves fine on Turbopack, and it's what the `_next-14-old` fixture does in a Next module.

## Minimal repro

1. A Next 16 app using `@harperfast/nextjs` (e.g. `npx create-harper my-app --template nextjs`).
2. Add `import 'harper';` at the top of a server action/component (as the README shows).
3. `harper run .` → Turbopack build fails (`Can't resolve 'harper'`) → all routes 404.
4. Remove the import and use the injected `tables` global instead → builds & serves fine.

Versions: `@harperfast/nextjs` 2.2.1, `next` 16.2.11, `harper` 5.1.22, Node 24.

## Suggestions

1. Add Turbopack externalization for `harper`/`harper-pro` in `withHarper()` (e.g. `turbopack.resolveAlias` / external config) so `import 'harper'` resolves under the v16 default bundler — or, if that's blocked upstream, default the plugin build to `webpack` on v16 with a warning.
2. Update the README to recommend the injected `tables` global **without** a top-level `import 'harper'` (or document that any such import must be lazy/request-time to avoid #37). The current guidance produces broken builds on v16.
3. Consider surfacing a failed startup build more loudly than a logged error + silent 404s (e.g. serve a 500 with the build error), so the failure mode is obvious on remote deploys.

Happy to open a PR for the docs change and/or test a Turbopack externalization approach if useful.

Contributor guide

Open the contributing guide

Research direction

Start with src/withHarper.cts and src/plugin.ts, then compare the README guidance around steps 5 and the next-16 and _next-14-old fixtures. Reproduce the Next 16 Turbopack build with the documented import and without it, and inspect the existing webpack and startup-error paths. Done means the documented server usage has an agreed working path, the relevant build behavior is covered or verified, and failures are no longer silently served as 404s.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, typescript
Domain
build-system, web-dev
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.