docs: add testing strategy for pre-publish verification

[jontsai]

Summary

• Add TESTING.md documenting the end-to-end testing pipeline for verifying package builds before publishing to npm
• Covers: build, pack, install tarball into consumer projects, verify on dev sites, break-fix test procedure
• Documents known gotchas (tsbuildinfo cache, Next.js .next cache, type:module incompatibility)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds comprehensive testing documentation for pre-publish verification of npm packages. The TESTING.md file documents the end-to-end pipeline from source code to live site verification, helping ensure package quality before publishing to npm.

Changes:

• Added TESTING.md with detailed pre-publish testing strategy
• Documented build, pack, install, and verification procedures
• Included break-fix testing methodology and known gotchas

Comments suppressed due to low confidence (2)

TESTING.md:81

• The statement about incremental: true being inherited from root tsconfig is inaccurate. Looking at tsconfig.json line 17, incremental: true is set in the root config, but packages/core/tsconfig.json line 7 explicitly sets composite: false, which overrides this. When composite: false, TypeScript doesn't create .tsbuildinfo files. The documentation should be updated to reflect that this gotcha only applies if composite: true is set in the package-level tsconfig.
  TESTING.md:77
• The documentation references hardcoded local paths like ~/code/skilletz/skilletz.cafe and ~/code/skilletz/tearekz.cafe which are specific to a particular development environment. While this may be intentional as internal documentation, consider whether this document should be more generic or if these paths should be documented in a separate internal-only file. The table on lines 74-77 also contains these environment-specific URLs.

cd /path/to/consumer-project
rm -rf node_modules/@hacktoolkit .next
npm install /path/to/hacktoolkit-nextjs-htk-X.Y.Z.tgz
make build

Repeat for each consumer project.

Verify: build completes successfully.

4. Verify on dev/staging site

If you have a dev or staging environment that serves from the docs/ directory (Next.js static export), make build immediately updates the live site. Verify with curl or a browser.

5. Break-fix test

To confirm the package is actually being used (not cached/stale):

1. Break: Modify a function in the package source (e.g., prefix buildFullAddress output with BROKEN-PKG-TEST)
2. Build + Pack: npx tsc && npm pack
3. Install: npm install /path/to/tarball.tgz
4. Rebuild consumer: rm -rf .next && make build
5. Verify broken: Check the built output or dev site and confirm the broken output appears
6. Fix: Revert the source change
7. Repeat steps 2-4
8. Verify fixed: Confirm the broken output is gone

Important: Always rm -rf .next before rebuilding - Next.js aggressively caches and may serve stale output.

Known Gotchas

• tsconfig.tsbuildinfo cache: If incremental: true is set (inherited from root tsconfig), tsc may skip emitting files if it thinks nothing changed. Always delete tsconfig.tsbuildinfo before a clean build.
• Next.js .next cache: Must rm -rf .next when testing package changes, otherwise the consumer build may use cached modules.
• "type": "module" incompatibility: The compiled TypeScript output uses extensionless imports (export * from './address'). Node.js ESM requires explicit extensions, so "type": "module" must NOT be set. Bundlers (Next.js/webpack) handle extensionless imports fine.
• npm tarball vs symlink: When installing from a tarball (npm install ./file.tgz), npm copies files. When using file: protocol in package.json, npm creates a symlink. The tarball test is closer to what real consumers experience from npm.

</details>



---

💡 <a href="/hacktoolkit/nextjs-htk/new/master?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

[Copilot]

The command npx tsc on line 18 may not work as expected in a pnpm workspace. Since this is a monorepo using pnpm (as evidenced by pnpm-workspace.yaml), the command should be pnpm tsc or pnpm build to ensure the correct TypeScript version from the workspace is used. The package.json line 31 also defines a build script that uses tsc directly, which should be invoked via pnpm build.

[Copilot]

Similarly, the command npx tsc && npm pack on line 62 should use pnpm instead of npx and npm for consistency with the pnpm workspace setup. It should be pnpm tsc && pnpm pack or pnpm build && pnpm pack.

[Copilot]

The commands use a mix of npm pack, npm install, and npx tsc throughout the document. For consistency with the pnpm workspace setup (evidenced by pnpm-workspace.yaml and CONTRIBUTING.md), these commands should use pnpm instead. Lines 26-27 should use pnpm pack, line 40 should use pnpm install, and line 63 should use pnpm install as well. While npm commands may work, using pnpm consistently is better practice in a pnpm workspace.

[Copilot]

The grep pattern '<title[^>]*>[^<]*</title>' on lines 51-52 will fail if the title tag spans multiple lines in the HTML output. A more robust approach would be to use grep -oz for multi-line matching, or simply check the HTTP status code with curl -I or verify the page loads without grepping for specific content. Consider documenting this limitation or providing an alternative command.