Skip to content

docs: Realign How it works around the hot-reload dev loop#650

Merged
developerjamiu merged 5 commits into
mainfrom
docs/how-it-works-566
Jun 25, 2026
Merged

docs: Realign How it works around the hot-reload dev loop#650
developerjamiu merged 5 commits into
mainfrom
docs/how-it-works-566

Conversation

@developerjamiu

Copy link
Copy Markdown
Contributor

Summary

Realigns the How it works page (#566) to lead with the developer experience, the serverpod start hot-reload dev loop, rather than internal request mechanics.

  • New structure: what you build → the dev loop → an AI-assisted workflow → choices at serverpod create → why it works → next steps.
  • Removes the request-lifecycle section and the mermaid sequence diagram (per Realign How it works with new the hot-reload workflow #566).
  • Documents the dev loop (one-command hot reload, embedded Postgres, no Docker by default), the optional AI-assisted workflow (editor agent skills + MCP server), and the serverpod create choices.
  • Surfaces the batteries-included differentiator: database, authentication, file uploads, caching, and real-time are built in.
  • Adds launch-pad links to the endpoints, models, sessions, streams, modules, and deployment docs.
  • Keeps the page name and slug (/how-it-works); does not introduce the "Jetstream" brand (per Realign How it works with new the hot-reload workflow #566).

Verification

  • Technical claims checked against the framework source: serverpod start behavior, embedded Postgres as the default (confirmed against a 3.5 project), the serverpod create choices, client.example.hello, and .spy.yaml.
  • markdownlint passes; no em dashes; cross-doc links use slug form.
  • I did not run npm run build locally (per AGENTS.md). Please confirm the cross-doc links resolve in the build, this page uses a custom /how-it-works slug, so the slug-form links are worth a build check.

Closes #566

@developerjamiu developerjamiu self-assigned this Jun 24, 2026
@developerjamiu developerjamiu added documentation Improvements or additions to documentation enhancement New feature or request labels Jun 24, 2026
@vlidholt

Copy link
Copy Markdown
Contributor

I think this page should function as a "quickstart" to understand how to work with Serverpod. Not how Serverpod works under the hood. What will the user need to know to get started as quickly as possible, without going through the getting-started guide? This is basically the page for more experienced Flutter developers who want to get started quickly.

Having a brief introduction at the top, as we do now, is great. But we must also dive a bit deeper into how you define a model and what you can pass to your methods. The old overview covers this pretty neatly. If we can take the good stuff from there and add it into this page, that would be ideal.

https://docs.serverpod.dev/overview

@vlidholt vlidholt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment above.

@developerjamiu developerjamiu requested a review from vlidholt June 25, 2026 09:49

@vlidholt vlidholt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Proposed some changes.

Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
Comment thread docs/04-get-started/03-how-it-works.md Outdated
@developerjamiu developerjamiu requested a review from vlidholt June 25, 2026 11:23

@vlidholt vlidholt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! 🥳

@developerjamiu developerjamiu merged commit f2ff8b0 into main Jun 25, 2026
4 checks passed
@developerjamiu developerjamiu deleted the docs/how-it-works-566 branch June 25, 2026 11:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Realign How it works with new the hot-reload workflow

2 participants