Skip to content

Change a sample

The Tasks and Library samples in this repository are checked by the same gate as the packages. Both samples commit generated metadata and co-located proxies, so a change to a decorated artifact has to be followed by a regeneration, or yarn ci fails. This page is for contributors to this repository; applications have their own scripts.

Run these from the repository root. The generate-proxies scripts run the proxy generator from its dist folder, so run yarn build first.

Command What it does
yarn workspace @cratis/arc.core.sample.tasks generate-proxies Regenerates Samples/Tasks/Features/generatedMetadata.ts, writes proxies beside its backend slices, and type-checks the proxies
yarn workspace @cratis/arc.sample.library generate-proxies Regenerates Samples/Library/Features/generatedMetadata.ts and proxies beside its backend slices
yarn check:metadata Fails when either sample’s committed metadata differs from its source
yarn check:proxies Fails when either sample’s committed proxies differ from regenerated output, or new proxies are untracked; run after both generate-proxies commands
yarn lint:tasks:arc Runs the Arc ESLint rules over Samples/Tasks/Features with type information
yarn test:client-generation Builds, regenerates the Tasks proxies, compiles the client fixtures, and runs the generated proxies against Express, Fastify, and Hono

Commit the regenerated files with the source change. Do not hand-edit generated metadata or browser proxies.

Arc for .NET exercises its hosts with two test applications in the Arc repository: TestApps/ArcCore, a standalone Arc.Core host, and TestApps/AspNetCore, an ASP.NET Core host with MongoDB and Swagger. Both share their features from TestApps/Shared. This repository has no test-app folders of the same name. Each behavior is covered by a sample, an adapter suite, or a contract check instead:

Behavior .NET reference (Arc 22.45.0) Arc for TypeScript Checked by
Standalone host without a web framework TestApps/ArcCore/Program.cs Samples/Tasks/main.ts with app.run() yarn build, yarn check:metadata
Route prefix, skipped namespace segments, and command name in route ArcCore/Program.cs options generatedApis options Source/Core/for_ArcApplicationBuilder/when_building_model_bound_routes
Model-bound command and read model Shared/ModelBoundCommand.cs, ModelBoundReadModel.cs Samples/Tasks RegisterTask and TaskItem; Samples/Library slices Slice specs under each sample’s for_* folders
Command validator AspNetCore/DoStuffValidator.cs TaskTitleValidator in Tasks; AddBookValidator in Library when_validating/with_an_empty_title, when_adding/with_an_empty_title
Query by argument, paging, and sorting Shared/Features/QueryShowcase Tasks taskById and allTasks; Library authorsPage when_performing/with_a_concept_argument, with_sorting_and_paging, Library when_paging
Observable queries Shared/Features/Ticker, LiveFeed, ObservableCollection, ChangeStream Tasks observeAllTasks (RxJS BehaviorSubject); Library allAuthors from Chronicle Tasks when_collecting/with_current_value; ContractTests/Client/observable-*.test.mjs over SSE, WebSockets, and the hub
Authentication handlers Shared/Authentication cookie and Microsoft identity platform handlers jwtBearer() and microsoftIdentityPlatform(); a native principal in the Library host Source/Core/authentication/for_*; Source/Express/for_identityHosts
Anonymous and authenticated queries, roles, and cross-cutting authorization filters Shared/Features/AuthenticationQueries, CrossCuttingAuthorization @roles('Librarian') in Library; authorization filters in Arc.Core Library with_librarian_role, without_librarian_role; yarn test:conformance
Host adapters AspNetCore/Program.cs (ASP.NET Core) @cratis/arc.express, @cratis/arc.fastify, @cratis/arc.hono; Library runs on Express Source/{Express,Fastify,Hono}/for_cratisArc; yarn test:client-generation runs generated proxies against all three
MongoDB collections and the change-stream watcher AspNetCore/Features/MongoWatcher @cratis/arc.mongodb observe() and MongoDBWatcher Source/MongoDB/run-integration.sh, including with_each_http_adapter
React frontend with generated proxies ArcCore/main.tsx, AspNetCore/main.tsx, Shared/Features/*Page.tsx Samples/Library/Features/**/*.tsx (app shell in Web/src) yarn workspace @cratis/arc.sample.library test:e2e exercises the proxies, not the browser UI
API description Swagger UI through Cratis.Arc.Swagger GET /openapi.json, without a bundled UI Source/Core/openApi/for_renderOpenApi

Three .NET behaviors have no counterpart by design:

  • Controllers. AspNetCore/Commands.cs, ObservableQueries.cs, and LiveFeedController.cs use ASP.NET controllers. Arc for TypeScript serves only model-bound and low-level operations; routes you add to your host sit beside Arc.
  • Cookie authentication. The shared CookieAuthenticationHandler is a .NET test fixture. Use your host’s session handling and a native principal.
  • FromRequest binding. It is C#-only; see OpenAPI.

Add a runnable sample only for a journey no sample, adapter suite, or contract check demonstrates yet, not to match a .NET folder name.

yarn ci runs all of the above with the rest of the gate. Contributing lists every step, and Prepare and publish a TypeScript release covers release checks and publication.