docs: correct introduction and quick-start against real framework#122
Open
antosubash wants to merge 3 commits intomainfrom
Open
docs: correct introduction and quick-start against real framework#122antosubash wants to merge 3 commits intomainfrom
antosubash wants to merge 3 commits intomainfrom
Conversation
Introduction:
- Replace the Program.cs snippet's generated-method calls with the
real public API (AddSimpleModule/UseSimpleModule) and clarify that
the source-generated helpers are invoked by them.
- Tech stack: Blazor SSR -> Inertia.js middleware (static HTML shell
with embedded JSON props); no Blazor in the rendering path.
- Fix Pages/index.ts example to use ./Browse (components live in
Pages/) and unknown over any.
Quick start:
- Module tree rooted at src/modules/ to match CLI's SolutionContext,
replacing fabricated Views/vite.config/package.json entries with
what sm new module actually creates (Constants/DbContext/Service
files, Endpoints/{Module}/GetAllEndpoint.cs, Events/, tsconfig,
test Unit/ + Integration/ folders).
- Add note that frontend scaffolding (Pages/, Views/) is created by
the first sm new feature, not by sm new module.
- Replace unsupported 'sm new feature Products/Browse' slash syntax
with 'sm new feature Browse --module Products' (+ interactive
fallback).
- Endpoint filename/class: BrowseProducts -> BrowseEndpoint to match
the CLI template ({Feature}Endpoint.cs).
- Pages/index.ts import uses the @/Views/ alias that the CLI emits.
Deploying simplemodule-website with
|
| Latest commit: |
2dca508
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://17bcb977.simplemodule-website.pages.dev |
| Branch Preview URL: | https://feature-xenodochial-hugle-86.simplemodule-website.pages.dev |
Covers all 33 pages under docs/site/ that contained factual drift from
the framework, CLI, modules, packages, and test projects. Findings
were validated against source files (framework/, modules/, cli/,
packages/, tests/, scripts/, Dockerfile*, docker-compose.yml,
template/) before editing.
Getting started / index
- index.md: drop "Blazor SSR" — the shell is served by ASP.NET Core +
Inertia.js middleware.
- project-structure.md: split CLI-scaffolded (src/modules/) vs
framework-repo (modules/) layouts; module/contracts dirs use the
SimpleModule.{Name} prefix; remove fictitious Views/, Data/Entities,
Services/, Dtos/ folders; reference the real Product/Request types;
csproj references SimpleModule.Hosting; Program.cs uses
AddSimpleModule/UseSimpleModule; expand npm workspaces list.
CLI (new-project, new-module, new-feature, doctor)
- new-project.md: add --dry-run and --framework-version options;
replace fictitious Api/Core/Database/Generator projects with the
real Host project; include the starter src/modules/Items module and
the scaffolded root files (package.json, biome.json, tsconfig.json,
.editorconfig, nuget.config, ClientApp/, Styles/, wwwroot/,
launchSettings); correct the run command.
- new-module.md: all paths use src/modules/; add --dry-run; add
tsconfig.json to the implementation tree; run command uses .Host.
- new-feature.md: add --no-view and --dry-run; document
Views/{Feature}.tsx + Pages/index.ts registry entry via @/Views/
alias; note that the CLI auto-adds the entry.
- doctor.md: replace "five categories" with the 12 real checks; --fix
also handles Pages/index.ts entries and npm workspace globs.
Guide A (modules, endpoints, contracts, events, inertia)
- modules.md: SimpleModule.{Name} project dirs; endpoints live in
Pages/ alongside components; csproj uses Microsoft.NET.Sdk +
FrameworkReference.
- endpoints.md: drop Endpoints/+Views/ split; IViewEndpoint classes
sit next to .tsx in Pages/.
- contracts.md: extract-ts-types writes types.ts into each module's
source dir.
- inertia.md: remove the fabricated Blazor SSR pipeline; document the
real HtmlFileInertiaPageRenderer (static wwwroot/index.html with
placeholder substitution); fix fallback version to build timestamp;
fix Pages/index.ts imports to ./Name.
Guide B (database, permissions, menus, settings, localization)
- database.md: fix the ApplyModuleSchema snippet to resolve
connectionString from dbOptions and call ApplyEntityConventions.
- permissions.md: replace the fictitious Admin/HasClaim handler with
the real HasPermission delegation; document wildcard matching.
- menus.md: add Roles and RequiredPermission to the MenuItem table;
drop the "MenuRegistry sorts by Order" claim; replace "Blazor
layout components" with React.
- settings.md: clarify DefaultValue is a raw string; fix
double-encoded example defaults.
- localization.md: split fallback behavior between React (returns
un-prefixed key) and .NET (returns null); note user-setting lookup
reads ClaimTypes.NameIdentifier only.
Guide C (ai-agents, background-jobs, file-storage, error-pages)
- ai-agents.md: Ollama key BaseUrl→Endpoint and llama3→llama3.2; note
Anthropic.Model is not wired; rewrite AddSimpleModuleAgents
description to reflect what it actually registers; Temperature is
float?; replace Agent SettingDefinitions with AgentOptions.
- background-jobs.md: drop TickerQ attribution — the module uses
Cronos + in-house DatabaseJobQueue/JobProcessorService/
StalledJobSweeperService; fix API routes and :guid constraints;
add WorkerMode and a split-deployment subsection;
GetRecurringCountAsync with CT defaults.
- file-storage.md: add CancellationToken = default to IStorageProvider
methods; S3.ServiceUrl example as null (Uri?); browse URL /files/;
IFileStorageContracts gets userId parameters and StoredFile
overloads.
- error-pages.md: no changes needed — verified against
SimpleModuleHostExtensions.
Frontend (overview, pages, styling, vite)
- overview.md: drop "Blazor SSR"; SimpleModule.Products/ project dir;
./Browse imports; rewrite resolvePage snippet to match the real
resolve-page.ts (throws on missing page).
- pages.md: SimpleModule. dir prefix; ./ imports; endpoint lives in
Pages/; replace "silently 404" with the real explicit-throw +
toast surface.
- styling.md: React TSX not Blazor Razor; swap primary/accent palette
to emerald #059669 / teal #0f766e with matching rgba shadows.
- vite.md: Vite 8 + Rolldown; import.meta.dirname; SimpleModule.
project dir and bundle names; full externals list (5 entries);
rolldownOptions; clarify dev:build is repo-root only.
Testing (overview, unit, integration, e2e)
- overview.md: NSubstitute is only used in select modules.
- unit-tests.md: ProductService takes IMessageBus; OrderFaker sets
UserId as a plain string; replace the fictitious
OrderCreatedAuditHandler/IAuditContext example with an IMessageBus
substitution pattern.
- integration-tests.md: fix the invalid named-arg+params C# call —
pass permissions positionally.
- e2e-tests.md: bump Playwright; reflect real playwright.config.ts
(retries 0, chromium only, CI launch-profile http, webServer timeout
120s, top-level timeouts); fix auth.setup.ts to navigate directly
to /Identity/Account/Login; correct page-object tree.
Advanced / reference (deployment, interceptors, source-generator,
type-generation, api, configuration, acknowledgments)
- deployment.md: rewrite Dockerfile to match the real 5-stage build
(Node 22, non-root appuser, DEPLOY_VERSION ARG); expand
docker-compose to api+worker+postgres:17 with healthcheck, shared
storage_data volume, and POSTGRES_PASSWORD/APP_BASE_URL template
vars; add OpenIddict__BaseUrl and BackgroundJobs__WorkerMode to the
env table; drop the false EnsureCreated claim.
- interceptors.md: document the three shipped interceptors
(EntityInterceptor, DomainEventInterceptor, EntityChangeInterceptor)
and soften the "never inject non-optional services" rule to match
the framework's own usage; rename example to IHasCreationTime/
IHasModificationTime.
- source-generator.md: HostingExtensionsEmitter emits both
AddSimpleModule and UseSimpleModule; drop the duplicate
ViewPagesEmitter entry; pass cancellation token in the Select
snippet.
- type-generation.md: output path includes the SimpleModule. project
dir prefix.
- api.md: add Roles and RequiredPermission to MenuItem.
- configuration.md: replace default appsettings.json with the real
shape (Storage, AI.Ollama, Agents, Rag.StructuredRag, Localization,
Passkeys); Ollama keys corrected; add OpenIddict, Passkeys, and
BackgroundJobs sections; docker-compose env vars include
OpenIddict__BaseUrl and BackgroundJobs__WorkerMode.
- acknowledgments.md: add Wolverine, Cronos, and Anthropic.SDK.
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.
Summary
Validated getting-started/introduction and getting-started/quick-start against the actual framework code and CLI. Fixed the inaccuracies below. Broader validation of the remaining 36 docs pages has been completed in the same session (findings not applied yet — separate follow-ups).
What changed
docs/site/getting-started/introduction.md
builder.AddSimpleModule()/await app.UseSimpleModule()) and clarifies thatAddModules/MapModuleEndpoints/CollectModuleMenuItemsare source-generated helpers invoked by those wrappers.Blazor SSR→Inertia.js (static HTML shell with embedded JSON props). The framework's rendering path does not use Blazor.Pages/index.tsexample: import path../Views/Browse→./Browse(the reference Products module keeps components inPages/).any→unknownto match real code.AddSimpleModule/UseSimpleModuleas the entry points that trigger the generated methods.docs/site/getting-started/quick-start.md
src/modules/Products/(matchesSolutionContext.ModulesPath = rootPath/src/modules).sm new moduleactually creates (Constants/DbContext/Service files,Endpoints/{Module}/GetAllEndpoint.cs,Events/,tsconfig.json, testUnit/+Integration/folders) instead of fabricated frontend files.Pages/,Views/,vite.config.ts, andpackage.jsonare created/modified by the firstsm new feature, not bysm new module.sm new feature Products/Browse(unsupported slash syntax) →sm new feature Browse --module Products, with a note about the interactive prompt.BrowseProducts.cs/BrowseProducts→BrowseEndpoint.cs/BrowseEndpoint(the CLI template emits{Feature}Endpoint.cs).'../Views/Browse'→'@/Views/Browse'(the aliasNewFeatureCommandemits). Comment path prefixed withsrc/.any→unknown.Why
Both pages drifted from the framework/CLI source of truth. The Program.cs snippet showed non-public helpers, the "Blazor SSR" claim is not what actually serves pages, the module tree advertised files the CLI never creates, and the
sm new featurecommand used aModule/Featureslash syntax that the CLI doesn't parse — anyone following the guide would hit failures on the very first module.Test plan
template/SimpleModule.Host/Program.cs,cli/SimpleModule.Cli/Infrastructure/SolutionContext.cs,cli/SimpleModule.Cli/Commands/New/NewModuleCommand.cs, andcli/SimpleModule.Cli/Commands/New/NewFeatureCommand.cssm new project Scratch && cd Scratch && sm new module Products && sm new feature Browse --module Productsand confirm the generated layout matches the new trees/snippets