@teispace/next-maker 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [2.1.1](https://github.com/teispace/npm-packages/compare/next-maker-v2.1.0...next-maker-v2.1.1) (2026-05-15)
+
+
+### Documentation
+
+* **next-maker:** add Recent changes + Known issues sections ([#82](https://github.com/teispace/npm-packages/issues/82)) ([069006a](https://github.com/teispace/npm-packages/commit/069006a858e13c3ffaf821ea9d10e8d32f0ecddd))
+
+## [2.1.0](https://github.com/teispace/npm-packages/compare/next-maker-v2.0.0...next-maker-v2.1.0) (2026-05-15)
+
+
+### Features
+
+* **next-maker:** add WebSocket setup service + manifest ([#79](https://github.com/teispace/npm-packages/issues/79)) ([7e2dc3f](https://github.com/teispace/npm-packages/commit/7e2dc3f72616309da18b6d815a60a7e727d571f8))
+* **next-maker:** add ws prompt + detection (data flow only) ([#78](https://github.com/teispace/npm-packages/issues/78)) ([f79c4d1](https://github.com/teispace/npm-packages/commit/f79c4d1002995ac0b3f55c1d1f4e96ee3788a6c2))
+* **next-maker:** cleanup WebSocket layer when opted out at init ([#80](https://github.com/teispace/npm-packages/issues/80)) ([4d3d421](https://github.com/teispace/npm-packages/commit/4d3d421a5056097f7fdefa88f2340f3523faa850))
+
+
+### Bug Fixes
+
+* **next-maker:** strip intl from seo.ts and sitemap.ts when i18n is off ([#75](https://github.com/teispace/npm-packages/issues/75)) ([a99d566](https://github.com/teispace/npm-packages/commit/a99d566ee634f551679525fff129bf62fcf0f578))
+* **next-maker:** sync http-client with universal/server entry split + bundle sentinel ([#77](https://github.com/teispace/npm-packages/issues/77)) ([cebc885](https://github.com/teispace/npm-packages/commit/cebc88569bbe3b65ccba9e40ea64fe8d262af908))
+
+
+### Documentation
+
+* **next-maker:** document ws feature + http universal/server entry split ([#81](https://github.com/teispace/npm-packages/issues/81)) ([e804700](https://github.com/teispace/npm-packages/commit/e80470001ec8ca03df2182e306340de4de0d6fbd))
+
 ## [2.0.0](https://github.com/teispace/npm-packages/compare/next-maker-v1.20.1...next-maker-v2.0.0) (2026-05-15)
 
 

package/README.md

@@ -76,7 +76,7 @@ npx @teispace/next-maker init my-app -y --package-manager pnpm
 | HTTP client | `fetch` |
 | dark mode, redux, i18n, tests, react-compiler | ✅ on |
 | pre-commit hooks, commitizen, copy `.env` | ✅ on |
-| docker, GitHub Actions, bundle-analyzer, community files (CODE_OF_CONDUCT etc.) | ⏭ off |
+| WebSocket (requires Redux), docker, GitHub Actions, bundle-analyzer, community files (CODE_OF_CONDUCT etc.) | ⏭ off |
 
 Anything you don't want? `next-maker remove <feature>` after init.
 
@@ -87,7 +87,7 @@ The starter at [`teispace/nextjs-starter`](https://github.com/teispace/nextjs-st
 | Section | Prompts |
 | --- | --- |
 | Identity | project name, description, author, version, support email, package manager, GitHub repo / issues / homepage |
-| Architecture | HTTP client (axios / fetch / both / none), dark mode, Redux Toolkit, i18n, testing, React Compiler, Bundle Analyzer |
+| Architecture | HTTP client (axios / fetch / both / none), dark mode, Redux Toolkit, WebSocket (requires Redux), i18n, testing, React Compiler, Bundle Analyzer |
 | Tooling | community files (CODE_OF_CONDUCT, CONTRIBUTING, SECURITY), README, Docker, CI/CD, pre-commit hooks (Husky/Commitlint/Lint-staged), Commitizen, copy `.env.example` → `.env` |
 | Templates | keep GitHub issue/PR templates? include `react-secure-storage`? |
 
@@ -100,7 +100,8 @@ The starter at [`teispace/nextjs-starter`](https://github.com/teispace/nextjs-st
 - Pino structured logger with redaction
 - Zod-validated env schema in `src/lib/env/`
 - Feature-based DDD architecture
-- Dual HTTP clients (`fetchClient` + `axiosClient`) on a shared foundation: runtime-aware cookie forwarding (browser jar in CSR, `next/headers` injection in RSC), automatic `X-Request-Id` correlation, single `parseApiError` pipeline, cookie-mode auth by default, typed query params via `{ params }`
+- Dual HTTP clients (`fetchClient` + `axiosClient`) on a shared foundation: two entry points (`@/lib/utils/http` universal, `@/lib/utils/http/server` for Server Components), automatic `X-Request-Id` correlation, single `parseApiError` pipeline, cookie-mode auth by default, typed query params via `{ params }`. A build-time `__bundle-sentinel__` rejects future regressions of the universal/server split.
+- WebSocket transport — **opt-in via the `ws` prompt** (requires Redux): typed `socket.io-client` wrapper, lazy singleton, `useWsEvent` / `useWsEmit` / `useWsStatus` hooks, Redux bridge into a dedicated (non-persisted) `wsReducer`. Cookie-mode auth by default; browser-only (SSR throws).
 - Hardened security headers in `next.config.ts`
 - `scripts/sync-env.ts` and `scripts/check-deprecated.ts` (used by the `validate` chain)
 
@@ -119,6 +120,7 @@ npx @teispace/next-maker setup [options]
 | `--http-client` | Adds the axios and/or fetch Result-based clients under `src/lib/utils/http/` |
 | `--dark-theme` | Installs `@teispace/next-themes` and adds `CustomThemeProvider` |
 | `--redux` | Redux Toolkit + `react-redux` + `redux-persist`, `StoreProvider`, `src/store` |
+| `--ws` | WebSocket transport — `socket.io-client@^4.8.3`, `src/lib/utils/ws/` subtree, non-persisted `wsReducer`, `attachWsBridge` mount in `StoreProvider`. Requires `--redux` to be installed first. |
 | `--i18n` | `next-intl` + `[locale]` routing + `proxy.ts` + `RootProvider` wiring |
 | `--tests` | Vitest + React Testing Library + jsdom + `test/test-utils.tsx` |
 | `--react-compiler` | `reactCompiler: true` in `next.config.ts` + `babel-plugin-react-compiler` |
@@ -135,6 +137,7 @@ npx @teispace/next-maker setup
 
 # Specific feature
 npx @teispace/next-maker setup --redux
+npx @teispace/next-maker setup --ws            # adds WebSocket layer (run after --redux)
 npx @teispace/next-maker setup --security-headers
 npx @teispace/next-maker setup --validate-scripts
 ```
@@ -747,6 +750,7 @@ my-project/
 │   │   ├── CustomThemeProvider.tsx    # (opt, dark-mode) @teispace/next-themes
 │   │   └── index.ts                   # Barrel — `next-maker provider <name>` keeps it sorted
 │   ├── store/                         # (opt, redux) makeStore, rootReducer, typed hooks
+│   │   └── slices/ws.slice.ts         # (opt, ws) non-persisted connection state slice
 │   ├── services/
 │   │   ├── api/                       # API service barrel
 │   │   └── storage/                   # react-secure-storage wrapper
@@ -758,11 +762,22 @@ my-project/
 │   │   ├── enums/
 │   │   └── utils/
 │   │       ├── http/                  # (opt, http-client)
-│   │       │   ├── shared/            # runtime detection, cookie injection, request-id, parseApiError, toSearchParams
+│   │       │   ├── shared/            # runtime guards, request-id, parseApiError, toSearchParams
 │   │       │   ├── axios-client/      # interceptors, token refresh, Result-based
 │   │       │   ├── fetch-client/      # same Result pattern on native fetch, typed `params`
+│   │       │   ├── __bundle-sentinel__/  # build-time regression gate ('use client' check)
 │   │       │   ├── client-utils.ts
-│   │       │   └── token-store.ts    # inert in cookie-mode (the default)
+│   │       │   ├── token-store.ts    # inert in cookie-mode (the default)
+│   │       │   ├── index.ts          # universal entry — safe in client/server/edge
+│   │       │   └── server.ts         # server-only entry — forwards next/headers cookies
+│   │       ├── ws/                    # (opt, ws) socket.io-client wrapper, hooks, Redux bridge
+│   │       │   ├── client/            # WsClient + lazy `wsClient` singleton (Proxy)
+│   │       │   ├── hooks/             # useWsStatus, useWsEvent, useWsEmit
+│   │       │   ├── redux/             # bridge (the only WS dispatcher) + selectors
+│   │       │   ├── shared/            # SSR guard, auth carrier, URL composer
+│   │       │   ├── types/             # ClientToServerEvents/ServerToClientEvents, payloads
+│   │       │   ├── constants.ts       # namespace, heartbeat, reconnection bounds
+│   │       │   └── index.ts           # public barrel
 │   │       └── validations/
 │   ├── i18n/                          # (opt, i18n) routing, request, navigation, translations/
 │   ├── styles/globals.css             # Tailwind v4 directives
@@ -791,7 +806,7 @@ my-project/
 └── package.json
 ```
 
-Features that have first-class opt-out prompts during `init`: `httpClient`, `darkMode`, `redux`, `i18n`, `tests`, `reactCompiler`, `bundleAnalyzer`, `docker`, `ci`, `preCommitHooks`, `commitizen`, `communityFiles`, `readme`, `copyEnv`. Each opt-out has a matching `setup --<feature>` to re-add later. `doctor` and `remove` cover the whole installed footprint via manifests.
+Features that have first-class opt-in/opt-out prompts during `init`: `httpClient`, `darkMode`, `redux`, `ws` (opt-in, requires `redux`), `i18n`, `tests`, `reactCompiler`, `bundleAnalyzer`, `docker`, `ci`, `preCommitHooks`, `commitizen`, `communityFiles`, `readme`, `copyEnv`. Each opt-out has a matching `setup --<feature>` to re-add later. `doctor` and `remove` cover the whole installed footprint via manifests.
 
 ---
 
@@ -799,7 +814,26 @@ Features that have first-class opt-out prompts during `init`: `httpClient`, `dar
 
 **CLI:** TypeScript, esbuild, Commander.js, Enquirer, Vitest, degit.
 
-**Generated apps:** Next.js 16+, TypeScript, Tailwind CSS v4, Biome, Pino, Zod, Redux Toolkit, `@teispace/next-themes`, next-intl, Fetch / Axios HTTP clients (shared foundation), Vitest + RTL, React Compiler.
+**Generated apps:** Next.js 16+, TypeScript, Tailwind CSS v4, Biome, Pino, Zod, Redux Toolkit, `@teispace/next-themes`, next-intl, Fetch / Axios HTTP clients (shared foundation), `socket.io-client` (opt-in via `ws` prompt), Vitest + RTL, React Compiler.
+
+---
+
+## Recent changes
+
+Behaviour added in **v2.1.0** beyond the headline features. None of these change the user-facing CLI surface — they harden parts of the generated app that previously needed manual cleanup.
+
+- **HTTP sentinel + server entry auto-align.** The template ships `src/lib/utils/http/__bundle-sentinel__/client-bundle-sentinel.tsx` and `src/lib/utils/http/server.ts` with imports of **both** axios and fetch client modules. When you pick a single client (at `init` or via `setup --http-client`), the inactive variant's directory is removed — and the two files would normally still reference it, breaking `yarn build`. Both are now rewritten in place to mention only the active client(s). Idempotent: re-running `setup --http-client` against the same configuration is a no-op.
+- **`remove ws` strips cleanly without manual intervention.** The WS manifest's reducer-registration and bridge-mount injections now carry `removePattern` functions, so `next-maker remove ws` deletes the `wsReducer` import, the `ws: wsReducer` entry, the unwrapped-on-purpose JSDoc, and the `attachWsBridge` `useEffect` block — without any "manual cleanup" messages. The init-time `cleanupWs` and the `remove ws` flow share the same pure helpers, so the byte-level output is identical.
+- **`useEffect` import auto-pruned.** When the WS bridge effect is stripped (init opt-out or `remove ws`), the `useEffect` import is dropped from `StoreProvider.tsx`'s React import line if no other `useEffect(` calls remain — avoiding the unused-import lint warning.
+- **Wording-tolerant strip helpers.** The `stripBundleSentinel`, `stripBridgeMount`, and `stripWsReducerRegistration` helpers now anchor on stable code tokens (import paths, function names, the `ws` + `persistReducer` keywords inside JSDoc) rather than literal comment text. Upstream template comment rewording can't silently break cleanup.
+- **`doctor` reports sentinel mount drift.** The HTTP manifest tracks the `<HttpClientBundleSentinel />` mount as a code injection in either `[locale]/layout.tsx` or `src/app/layout.tsx`. If you delete the mount manually, `doctor` reports it; `remove http-client` strips it.
+
+---
+
+## Known issues
+
+- **`setup --redux` post-init when `ws` was opted out.** The template's `StoreProvider.tsx` ships with the WS bridge mount inline. `next-maker setup --redux` copies the template's `StoreProvider.tsx` wholesale into the project — so running it on a project where `ws` is **not** wanted leaves `import { attachWsBridge, wsClient } from '@/lib/utils/ws'` in place, and `yarn build` fails because that module doesn't exist. Workaround until a fix lands: also run `next-maker setup --ws` to install the WS layer, then `next-maker remove ws` if you don't actually want it (clean removal handles both layers). Tracked separately; out of scope for v2.1.0.
+- **`doctor --fix` is interactive.** Some setup services (notably `setup --http-client`) prompt for an action when the feature is partially installed. `doctor --fix` invokes `apply()` directly, so the prompt fires during what's meant to be a non-interactive repair. Workaround: run the specific `setup --<feature>` manually and pick the appropriate action. A non-interactive repair path is on the roadmap.
 
 ---
 
@@ -849,6 +883,7 @@ node ../dist/index.js test src/hooks/useDebounce.ts --force
 
 # Maintenance
 node ../dist/index.js doctor
+node ../dist/index.js setup --ws            # add WebSocket layer (project must already have --redux)
 node ../dist/index.js remove redux --dry-run
 ```