docs: refresh README + guides; reframe around the typed operational model#51
Open
Pom4H wants to merge 3 commits into
Open
docs: refresh README + guides; reframe around the typed operational model#51Pom4H wants to merge 3 commits into
Pom4H wants to merge 3 commits into
Conversation
Rewrites README, homepage, and "What is tsops?" guide to lead with the actual differentiator vs Helm/CDK8s/Pulumi: the same tsops.config.ts is imported by both the manifest builder and the application code, so renaming an app or changing a port is caught by the TypeScript compiler in every caller. - README: product-topology-first framing, comparison table, honest trade-offs, agent-safety note - docs/index.md: hero/why-grid restructured around runtime-import story - docs/guide/what-is-tsops.md: replaces YAML-vs-tsops framing with the "Kubernetes-first vs product-topology-first" inversion - docs/guide/getting-started.md: adds runtime-import section, fixes stale yourusername GitHub links - docs/examples/index.md: points at real examples/ dir in this repo
- Drop sidebar entries pointing at pages that don't exist (configuration, networking, building, secret-validation, multi-environment, monorepo, cicd, api/define-config, api/context-helpers, api/cli). Add Preview Overlays in their place. - Replace /guide/contributing link with the CONTRIBUTING.md on GitHub. - Replace yourusername.github.io and ghcr.io/yourorg placeholders with pom4h.github.io and ghcr.io/example. - Promote Bun to first-class install option alongside pnpm; bump prerequisites to Node.js 20+/22 LTS or Bun 1.1+ (Node 18 EOL'd in April 2025).
5 tasks
There was a problem hiding this comment.
Pull request overview
Refreshes tsops’ user-facing documentation to emphasize the “typed operational model” differentiator (same tsops.config.ts used for manifests and imported by application code), while pruning/repairing links and modernizing install/runtime guidance (Bun + Node 20+/22).
Changes:
- Reframes README and VitePress homepage/guide copy around the runtime-import story + adds comparison/trade-offs sections.
- Updates install instructions (pnpm/bun/npm; removes yarn) and prerequisites (Node 20+/22 LTS or Bun 1.1+).
- Prunes/repairs broken docs links and updates VitePress sidebar navigation.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Rewritten top-level pitch + quick start focusing on “typed operational model” and runtime import. |
| docs/index.md | Homepage refresh: new differentiator section, comparison/trade-offs, updated CTAs and install blocks. |
| docs/guide/what-is-tsops.md | Reframed “What is tsops?” guide around topology-first model + runtime config import story. |
| docs/guide/getting-started.md | Updated prerequisites/install guidance; adds “use config from your app” section and fixed GitHub links. |
| docs/guide/quick-start.md | Adds install code-group and updates example registry placeholder. |
| docs/examples/index.md | Updates examples page to point to repo examples/ and adds a “runnable examples” section. |
| docs/README.md | Fixes live docs URL. |
| docs/.vitepress/config.ts | Sidebar prune and fixes Contributing link to the GitHub file. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **Startups** - Need to move fast with confidence | ||
| - **Teams tired of YAML** - Want type safety and better DX | ||
| - **`tsops plan`** — diff the cluster against your config, validate every secret, list orphans. Errors fail the command. | ||
| - **`tsops deploy`** — apply the planned manifests atomically. Prune orphans tagged `tsops/managed=true`. |
Comment on lines
+30
to
+31
| > tsops itself is runtime-agnostic — the CLI runs on either Node.js or Bun. | ||
| > Pick whichever your project already uses. |
| pnpm tsops plan | ||
| git clone https://github.com/Pom4H/tsops | ||
| cd tsops && pnpm install | ||
| pnpm --filter @example/fullstack tsops plan |
| ``` | ||
|
|
||
| Then create a `tsops.config.ts` file: | ||
| Rename an app, change a port, move a service to another namespace — the TypeScript compiler finds every caller in your codebase. No more "wrong service name → 502 in preview". |
| tsops deploy --namespace prod --app api | ||
| tsops plan --namespace prod # diff cluster vs config, validate secrets, list orphans | ||
| tsops build --app api # build & push images | ||
| tsops deploy --namespace prod # apply atomically, prune orphans |
Comment on lines
+59
to
+62
| Rename an app, change a port, add a namespace — the TypeScript compiler finds every caller in your codebase. `worken-api` is no longer repeated in seven places that drift independently. | ||
|
|
||
| This is what separates tsops from Helm, Kustomize, CDK8s, and Pulumi: **the deploy config and the application's runtime config are the same typed object**. | ||
|
|
| ```bash | ||
| tsops plan --namespace prod # validate, diff, list orphans | ||
| tsops build --app api # build & push image | ||
| tsops deploy --namespace prod # apply atomically |
| ``` | ||
|
|
||
| ### 🎯 Type Safety | ||
| If you rename the `api` app to `core-api` in `tsops.config.ts`, every caller of `config.url('api', ...)` becomes a compile error. Same for `config.env('api', 'JWT_SECRET')` if `JWT_SECRET` disappears from the secret. That's the core idea. |
This was referenced May 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Renews the user-facing docs around the actual differentiator vs Helm / CDK8s / Pulumi: the same
tsops.config.tsis imported by both the manifest builder and the application code. Renaming an app or changing a port becomes a compile error in every caller.Also kills broken links and modernizes install instructions for the 2026 ecosystem (Bun first-class, yarn removed, Node 20+/22 LTS).
Changes
Reframe (README + homepage + "What is tsops?")
Broken links / placeholders
configuration,networking,building,secret-validation,multi-environment,monorepo,cicd,api/define-config,api/context-helpers,api/cli,guide/contributing).Preview Overlayspage in its place./guide/contributinglink with the realCONTRIBUTING.mdon GitHub.yourusername.github.ioandghcr.io/yourorgplaceholders withpom4h.github.io/ghcr.io/example.tsops-examplesrepo reference indocs/examples/index.mdwith the realexamples/directory in this repo.2026 / Bun
Files touched
README.mddocs/index.mddocs/README.mddocs/.vitepress/config.ts(sidebar prune)docs/guide/what-is-tsops.mddocs/guide/getting-started.mddocs/guide/quick-start.mddocs/examples/index.mdOut of scope
engines: { node: ">=18.0.0" }field in published packages is stale but bumping it is a runtime change, not a docs change. Filed as a separate concern.configuration,networking, etc.) — those should be written from scratch when there's content for them, not stubbed to satisfy a sidebar.Test plan
pnpm docs:dev— sidebar navigates without 404spnpm docs:build— VitePress build succeeds with no dead-link warnings (project already hasignoreDeadLinks: trueso this is best-effort)Generated by Claude Code