From 055f230093f3f5c4ff12cc4b4033141f50361d84 Mon Sep 17 00:00:00 2001 From: Brandon Corbett Date: Tue, 6 Oct 2026 22:56:41 -0400 Subject: [PATCH] docs: add a Start here section to the root and package READMEs Point new readers at the docs quickstarts (Docker self-hosted first, managed second) and the compatibility matrix before the repo-specific setup. The root README also shows the ecosystem topology as a Mermaid diagram with the backend node highlighted, so it is clear where these packages sit between the client SDKs and the auth API. The core, express, fastify, and nextjs package READMEs ship to npm, so they get the short paragraph only, without the diagram, to keep the npm pages short. They pick it up on the next release. Refs fells-code/seamless-auth-docs#45 --- README.md | 18 ++++++++++++++++++ packages/core/README.md | 4 ++++ packages/express/README.md | 4 ++++ packages/fastify/README.md | 4 ++++ packages/nextjs/README.md | 4 ++++ 5 files changed, 34 insertions(+) diff --git a/README.md b/README.md index aebe93a..11ec3b4 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,24 @@ It provides a small, explicit core and framework-specific adapters that make it This repository contains the core building blocks and official server-side framework integrations. +## Start here + +New to Seamless Auth? The [self-hosted quickstart](https://docs.seamlessauth.com/start/quickstart/) runs the full stack locally with Docker. If Seamless hosts your auth instance, follow the [managed quickstart](https://docs.seamlessauth.com/start/managed-quickstart/) instead. + +This repo is the backend layer: the core and framework adapters your server mounts at `/auth` to carry browser cookies and native bearer tokens to the auth API. + +```mermaid +flowchart LR + browser["Browser
@seamless-auth/react"] -- "signed httpOnly cookies" --> backend + native["Native app
@seamless-auth/react-native"] -- "bearer tokens" --> backend + backend["Your backend
@seamless-auth/express, fastify, or nextjs
mounted at /auth"] -- "bearer token + service token" --> api + api["seamless-auth-api
owns the session"] --> db[("Postgres")] + backend -. "verifies tokens with JWKS" .-> api + style backend stroke-width:3px +``` + +[How the pieces connect](https://docs.seamlessauth.com/start/overview/#how-the-pieces-connect) explains each hop. [Compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together. + --- ## Philosophy diff --git a/packages/core/README.md b/packages/core/README.md index fbb4d80..65635b5 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -16,6 +16,10 @@ It is designed to be: If you are building a custom adapter (Express, Fastify, Next.js, Hono, etc.), this is the package you integrate with. +## Start here + +New to Seamless Auth? The [self-hosted quickstart](https://docs.seamlessauth.com/start/quickstart/) runs the full stack locally with Docker. If Seamless hosts your auth instance, follow the [managed quickstart](https://docs.seamlessauth.com/start/managed-quickstart/) instead. The [compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together. + --- ## What This Package Is diff --git a/packages/express/README.md b/packages/express/README.md index 3da4433..6f41207 100644 --- a/packages/express/README.md +++ b/packages/express/README.md @@ -26,6 +26,10 @@ Pair this with: - **React SDK:** https://github.com/fells-code/seamless-auth-react - **Starter app:** https://github.com/fells-code/seamless-cli +## Start here + +New to Seamless Auth? The [self-hosted quickstart](https://docs.seamlessauth.com/start/quickstart/) runs the full stack locally with Docker. If Seamless hosts your auth instance, follow the [managed quickstart](https://docs.seamlessauth.com/start/managed-quickstart/) instead. The [compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together. + --- ## Installation diff --git a/packages/fastify/README.md b/packages/fastify/README.md index 61c96ba..108852b 100644 --- a/packages/fastify/README.md +++ b/packages/fastify/README.md @@ -8,6 +8,10 @@ cookies they depend on, so the browser talks to your origin and never holds a token itself. The decisions all live in `@seamless-auth/core`; this package binds them to Fastify. +## Start here + +New to Seamless Auth? The [self-hosted quickstart](https://docs.seamlessauth.com/start/quickstart/) runs the full stack locally with Docker. If Seamless hosts your auth instance, follow the [managed quickstart](https://docs.seamlessauth.com/start/managed-quickstart/) instead. The [compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together. + ## Install ```sh diff --git a/packages/nextjs/README.md b/packages/nextjs/README.md index 634d653..8ee496e 100644 --- a/packages/nextjs/README.md +++ b/packages/nextjs/README.md @@ -10,6 +10,10 @@ in server components and `proxy.ts`. The decisions all live in `@seamless-auth/core`; this package binds them to web-standard `Request` and `Response`. +## Start here + +New to Seamless Auth? The [self-hosted quickstart](https://docs.seamlessauth.com/start/quickstart/) runs the full stack locally with Docker. If Seamless hosts your auth instance, follow the [managed quickstart](https://docs.seamlessauth.com/start/managed-quickstart/) instead. The [compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together. + ## Install ```sh