Refactor Genkit docs for app-centric quickstart experience#282
Closed
chrisraygill wants to merge 15 commits into
Closed
Refactor Genkit docs for app-centric quickstart experience#282chrisraygill wants to merge 15 commits into
chrisraygill wants to merge 15 commits into
Conversation
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
chrisraygill
changed the title
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive quickstart guides and code snippets for integrating Genkit with various frontend and backend frameworks (including Angular, Astro, Next.js, Nuxt, React, Remix, SvelteKit, TanStack Start, Chi, Django, Echo, Express, FastAPI, Fastify, Flask, Gin, Hono, NestJS, net/http, and Shelf). It also adds reusable components like FrameworkCard and PackageManagerTabs, updates styles, and enhances utility scripts for document processing and routing. The reviewer identified two important issues: a regex limitation in PackageManagerTabs.astro that fails to match bare npm install commands, and a parsing bug in content-processor.ts where trailing comments on ESM statements can prevent correct detection of the end of the statement.
chrisraygill
force-pushed
the
integrate-framework-frontend-nav
branch
from
84c3688 to
3d0c5af
Compare
Reorganizes the app-frameworks and backend-frameworks docs, adds a 'Choose your stack' entry point, framework icon assets, FrameworkCard and PackageManagerTabs components, language-specific page generation, and the associated landing/sidebar/navigation styling changes.
chrisraygill
force-pushed
the
integrate-framework-frontend-nav
branch
from
178d8da to
8aedf3d
Compare
…-your-stack Align all app-framework and backend-framework tutorial guides to a single canonical structure modeled on app-frameworks/angular.mdx: add 'What you'll build' and 'What you built' sections everywhere, standardize headings (Set up the application / Create the backend / Test and inspect the app / Build the <Framework> UI), and align shared intro copy, while preserving each framework's idiomatic code and framework-specific sections (Choose an integration path, Serving models, etc.). Add connective prose to choose-your-stack.mdx explaining how developers proceed through the guides: every guide builds the same Bargain Chef example, the two kinds of guides (app vs backend) for JS, and the backend-first then optional-frontend path for Go/Dart/Python.
…ions
Rename all framework guide titles from "<Framework> quickstart" to
"<Framework> tutorial" and update in-body self-references ("this guide",
"In this guide") to "tutorial" so every guide consistently refers to itself
as a tutorial. Left the get-started Quickstart page references and the
/quickstarts/ sample URLs untouched.
Add Angular-style language-specific frontmatter descriptions (default + js +
go/dart/python) to the multi-language app-framework guides (Astro, Next.js,
Nuxt, React, Remix, SvelteKit, TanStack Start) so each language variant gets
an accurate description. Single-language backend guides keep one description.
…age scripts Restructure the Astro tutorial to follow the Angular tutorial: - Remove @genkit-ai/middleware install + the stale retry-middleware prose. - Full-stack JS imports the flow types via `import type`; non-JS hand-writes interfaces. Add the Angular-style "expected flow shape" reference block. - Drop the standalone-JS tab and "Choose an integration path"; use the linear happy path plus an "Already have a standalone backend?" aside and a "Use a standalone backend instead" section at the end. - Copy the "Prefer a different model?" aside, the agent-skills optional section, and the Developer UI demo video. - Follow Angular wording for the flow explanation, corsCallout, the JS value-proposition sentence, and prerequisites. Inline both page-script variants as code blocks (matching how Angular inlines its component) and remove the now-unused _snippets/astro-page-script.ts and _snippets/angular-app.ts.
Apply the same conformance pass used on Astro to the remaining tutorials. App-framework tutorials (nextjs, nuxt, react, remix, sveltekit, tanstack-start): - Remove stale @genkit-ai/middleware / retry references that did not match the rendered flow code. - Full-stack JS imports the flow types via `import type`; non-JS hand-writes interfaces, with an "expected flow shape" reference block. - Replace standalone-vs-in-project JS tabs with the linear happy path plus an "Already have a standalone backend?" aside and a "Use a standalone backend instead" end section (kept Next.js App/Pages Router fork; React stays standalone-only). - Add the "Prefer a different model?" aside, agent-skills section, and Developer UI demo video; use Angular-style flow explanation, corsCallout, JS value-proposition sentence, and wording/punctuation. - Inline UI components as code blocks; remove the now-unused Next.js page snippets. Backend-framework tutorials (chi, django, echo, express, fastapi, fastify, flask, gin, hono, nestjs, nethttp, shelf): - Add the model aside, agent-skills section, and Developer UI video; adopt the Angular-style flow explanation and wording. Keep legitimate retry/middleware usage where the rendered code actually uses it.
- express/hono: add .js extension to relative imports (NodeNext build). - nestjs: import type for Request/Response; cast Readable.fromWeb body. - django: SSE branch used result.response.model_dump() -> result.model_dump(). - chi/nethttp: replace non-building value.Response.Output(&final) with final = value.Output, and drop the dead `if sendChunk != nil` guard (matches the gin reference pattern). - echo: same sendChunk guard fix; add missing go get for plugins/googlegenai. - flask: use uv add / uv run instead of pip install / python (uv-managed env). - hono: complete the package-explanation list, note scaffold-provided deps, remove a duplicate curl block. - sveltekit: match the sv create wizard wording for the TypeScript prompt. - backend flow snippet: reword stray "Angular component" comment. - astro/react: drop the "Express integration" copy-paste port note.
…Stack/Fastify - Remove retry/@genkit-ai/middleware from the backend flow snippet, the express inline flow, and the hono/fastify/nestjs install lists + prose. The backend snippet is now identical to the app snippet (no middleware; exports the shared Recipe/PartialRecipe/BargainChefInput types). - Go (chi/echo/nethttp): convert the streaming flow to the pointer pattern (*Recipe / GenerateDataStream[*Recipe] / final = value.Output / guard value.Chunk != nil), matching the working gin reference. The earlier value-type + nil-check combo did not compile. - Next.js App Router: streamFlow<Recipe, PartialRecipe> on @genkit-ai/next/client is invalid (single Action generic); use streamFlow<typeof bargainChefFlow> so types are shared from the backend. - Fastify: replace the fictional `npm init fastify` "TypeScript-friendly setup" with a hand-rolled ESM setup matching the sample. - Remix/TanStack: replace deprecated create-remix / wrong create-start scaffolders with current ones and the current TanStack server-route API.
Drop the Genkit generation/retry middleware so the entire backend tutorial set
is middleware-free, matching the JS tutorials and the app snippet:
- Go (chi/echo/gin/nethttp): remove the plugins/middleware import + go get, drop
&middleware.Middleware{} from genkit.WithPlugins, remove the
ai.WithUse(&middleware.Retry{...}) line, and the retry prose. Framework
middleware (echo logger/CORS, chi logger) is preserved.
- Dart (shelf): drop RetryPlugin() and use: [retry(maxRetries: 3)].
These quickstarts shouldnt cover serving a raw model as a remote endpoint; the Express snippet was also broken (oai.model instance call, awaited, and expressHandler given a ModelReference). Drop both sections and the now-dangling #serving-models links from the models guide.
- Add "You can find the finished code on GitHub" links (same copy as Angular) to every backend guide and fix the app-guide links to the working /tree/main/ form, pointing at each tutorial subdirectory in genkit-ai/samples. - Fastify and NestJS: install genkit-cli as a dev dependency instead of globally (-g), matching the rest of the JS tutorials. - Fix mashed bullets / imports / headings left by the earlier middleware-removal edits in express/hono/fastify/nestjs.
Express now imports the shared _snippets/bargainChefFlow.ts via ?raw like hono, fastify, and nestjs, instead of inlining its own copy. Drop the unused Recipe/PartialRecipe/BargainChefInput type exports (no guide imported them, and a separately-deployed frontend cannot import across project boundaries) and the prose bullets describing them. Standardize all four guides on a src/genkit/ directory for the flow file.
- Remix: use the default React Router v7 config routing (no @react-router/fs-routes); edit app/routes/home.tsx and register the resource route in app/routes.ts. Use fetchHandler (single flow) instead of fetchHandlers with a path prefix, which served the flow at /api/bargainChefFlow/bargainChefFlow. - TanStack Start: update paths to the current CLI layout (src/routes, src/genkit, @/ alias) and use fetchHandler in the server route.
Make the CORS framing consistent across all backend tutorials. Every guide already enables all origins out of the box; this clarifies that intent and tells readers to restrict origins before deploying. - NestJS: present CORS as a default setup step rather than optional. - All guides: add a short note that the setup allows all origins for local development and how to lock it down for production.
Collaborator
Author
|
Superseded by #293, which moves the branch into the main genkit-ai/docsite repo (same branch, now hosted here instead of the fork). |
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
1 participant
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.
No description provided.