← Documentation index
Everything is configured through the callback passed to AddJsxCore:
builder.AddJsxCore(options =>
{
options.DefaultRenderMode = RenderMode.Server;
options.Globals.Register<InventoryService>("Inventory");
});
| Option |
Default |
Purpose |
ViewsDirectory |
"Views" |
Where views live, relative to the content root |
WorkingDirectory |
"obj/JsxCore" |
Compiler output; gitignored and hidden from project trees |
RequestPath |
"/_jsx" |
Base path compiled modules are served from |
WebRootDirectory |
the host's web root, else "wwwroot" |
What rooted asset imports resolve against |
Extensions |
.tsx, .jsx |
File extensions treated as views, in probe order |
ViewLocationFormats |
{Views}/{controller}/{view}, {Views}/Shared/{view}, {Views}/{view} |
How a view name maps to a path |
AreaViewLocationFormats |
area-aware equivalents |
Tried first when the request has an area |
| Option |
Default |
Purpose |
DefaultRenderMode |
Client |
Mode used when neither the result nor the view's directive names one |
EnableReactCompatibility |
true |
In Preact mode, map react/react-dom to preact/compat |
ViewEngineOrder |
0 |
Position among MVC view engines; 0 beats Razor |
JsonSerializerOptions |
web defaults |
How the model is serialised, and the basis for generated types |
| Option |
Default |
Purpose |
TypeChecking |
Warn |
Off, Warn or Error |
CompileOnStartup |
true |
Compile everything during startup |
PrecompiledOnly |
follows the build |
Serve prebuilt output with no toolchain. On for Release, off for Debug; set it to override |
WatchForChanges |
dev only |
Recompile when sources change |
HotReload |
dev only |
Serve the hot reload client and endpoint |
AutoInstallDependencies |
Development |
Never, Development or Always: when startup may restore packages. The build restores in any configuration |
Minify |
follows the build |
Minify served JavaScript. Null takes the project file's answer |
MinifierPath |
auto |
Explicit path to the esbuild binary |
CompressAssets |
follows the build |
Compress asset responses. Null takes the project file's answer |
SourceMaps |
follows the build |
Emit source maps for compiled views. On for Debug, off for Release, because the maps carry the view's own TypeScript |
NpmPath |
auto |
Explicit path to npm |
DependencyInstallTimeout |
5 minutes |
Limit for a single npm command |
OnBootstrapMessage |
console |
Where install progress is reported |
TypeScriptCompilerPath |
auto |
Explicit compiler path, skipping discovery |
AdditionalToolchainSearchPaths |
empty |
Extra roots to search for node_modules |
MinimumTypeScriptMajorVersion |
7 |
Lowest acceptable compiler version |
CompilerOptions |
empty |
Extra options merged into the generated tsconfig |
GenerateEditorTsConfig |
true |
Write a tsconfig beside the views for editors |
WatchForChanges and HotReload are bool?. null means "on in Development, off elsewhere".
| Option |
Default |
Purpose |
ImportMap |
empty |
Extra bare specifier mappings for the browser, which win over generated ones |
AllowNodeModules |
true |
Let views import npm packages, server and browser |
PackageManager |
unset (native) |
Name a client: native needs nothing installed, npm runs the npm on the machine |
Globals |
empty |
.NET objects exposed to server-rendered views |
ContextValues |
empty |
Values added to every view's context prop |
AutoExport |
convention |
Which .NET types get TypeScript declarations |
| Option |
|
Document |
The generated HTML shell |
ServerRendering |
JavaScript engine limits |
TypeDefinitions |
Generated type settings |
Controls the HTML wrapper. Most of these can also be
set per response.
| Option |
Default |
Purpose |
ContainerId |
"jsxcore-root" |
Element the view renders into |
ModelElementId |
"jsxcore-model" |
Script tag holding the serialised model |
Language |
"en" |
lang attribute on <html> |
DefaultTitle |
"" |
Title when a view exports none |
HeadContent |
"" |
Raw markup appended to <head> |
Nonce |
none |
Per-request CSP nonce for the scripts JsxCore writes |
BodyContent |
"" |
Raw markup appended to <body> |
BodyAttributes |
empty |
Attributes on <body> |
Template |
none |
Replaces the document writer entirely |
| Option |
Default |
Purpose |
Timeout |
5 seconds |
Wall clock limit for a single render |
MaxRecursionDepth |
256 |
Guards runaway recursion |
MaxPooledEngines |
processor count |
Concurrent server renders before queueing |
ExposeCamelCaseMembers |
true |
Expose .NET members under camelCase aliases too |
| Option |
Default |
Purpose |
Enabled |
true |
Generate TypeScript from .NET types at all |
AutoExport |
null |
A TypeSource; null means the built-in convention |
ConventionalNamespaceNames |
Models, ViewModels |
Namespace segments treated as holding view models |
ApplicationAssembly |
from the environment |
Assembly the convention scans |
OutputPath |
obj/JsxCore/types |
Where declarations are written |
MirrorNamespaces |
true |
One TypeScript namespace per .NET namespace |
TrimNamespacePrefix |
null |
Strip a root namespace from generated names |
EnumsAsStrings |
null |
null follows the enum converter |
IncludeFields |
false |
Include public fields as well as properties |
Add<T>() |
n/a |
Register a type explicitly, alongside AutoExport |
The specifier is not configurable. See Model types for the TypesFrom
factories.
| Specifier |
Holds |
dotnet:types |
Every type generated from .NET, reached through its .NET namespace |
dotnet:types/MyApp/Models |
The same types, imported by name from the namespace they live in. The .NET namespace with its dots as slashes, so MyApp.Models is MyApp/Models |
dotnet:globals |
The .NET objects registered with options.Globals, one named export each |
dotnet:rendering |
isServerRender, and the types a view is handed: ViewProps, HeadDescriptor, JsxNode |
dotnet:rendering/head |
The <Head> component |
@jsxcore/client |
mountView, resolved to whichever framework the project builds against |
One rule: dotnet: is the .NET side of the application: types, globals and rendering. It is not an npm package and
does not resolve like one; the browser is told about it through the import map, and TypeScript through
paths. Reserved names are matched first and win over an assembly of the same name, which a
PascalCase assembly cannot collide with anyway. See Import syntax.
| Method |
Lifetime |
Register<TService>(name?) |
Resolved per render from the request's service scope |
Register(name, instance) |
One shared instance, which must be thread-safe |
Register(name, factory) |
Whatever your factory decides |
Remove(name) |
Unregister |
See .NET interop.
Set these in your .csproj. They control build-time compilation.
| Property |
Default |
Purpose |
JsxCoreCompileOnBuild |
true |
Compile views during dotnet build and dotnet publish |
JsxCoreTypeChecking |
warn |
error, warn or off |
JsxCoreFramework |
preact |
preact ships inside JsxCore; react is restored from npm by the build |
JsxCoreViewsDirectory |
Views |
Where views live |
JsxCoreManifestDirectory |
beside the project |
Directory holding the package.json to use, for a solution sharing one |
JsxCoreWorkingDirectory |
$(BaseIntermediateOutputPath)JsxCore\ |
Compiler output |
JsxCoreWebRootDirectory |
wwwroot |
What rooted asset imports resolve against |
JsxCoreAutoInstallDependencies |
true |
Install missing npm packages during the build |
JsxCoreMinify |
Release only |
Minify what is served to the browser, with esbuild |
JsxCoreCompressAssets |
Release only |
Compress assets on the way out: Brotli, or gzip |
JsxCorePrecompiled |
Release only |
Serve the views the build compiled instead of compiling at startup |
JsxCoreSourceMaps |
Debug only |
Emit source maps beside compiled views. Off for Release: a map inlines the view's .tsx source and is served from the same prefix as the view |
JsxCoreMinifierPath |
auto |
Explicit path to the esbuild binary |
JsxCoreNpm |
probed |
Path to npm, if it is not on PATH |
JsxCorePackageManager |
native |
native talks to the registry directly; npm shells out to npm |
JsxCoreUseNpm |
false |
Shorthand for JsxCorePackageManager=npm |
JsxCoreGenerateModelTypes |
true |
Generate TypeScript declarations from .NET models during the build |
JsxCoreEmitViewLocationAnnotations |
true |
Emit the annotations that let an IDE resolve View() calls |
JsxCoreViewExtensions |
.tsx;.jsx |
Extensions those annotations describe |
JsxCoreViewLocationFormats |
as ViewLocationFormats |
Semicolon-separated, for those annotations |
JsxCoreAreaViewLocationFormats |
as AreaViewLocationFormats |
Semicolon-separated, for those annotations |
JsxCoreAdditionalSearchPaths |
empty |
Extra roots to search for node_modules, as pnpm needs |
JsxCoreCompilerPath |
auto |
Explicit path to the TypeScript binary |
JsxCoreGenerateEditorTsConfig |
true |
Write the editor tsconfig at build time |
JsxCoreToolPath |
in the package |
The build tool the targets invoke, under tools/net8.0/ |
JsxCoreToolCommand |
dotnet exec ... |
How that tool is run, if you need to change the host |
The last four view-location properties describe where views live to the source generator, which
emits the annotations an IDE reads to resolve a View() call returning a .tsx file. They have no
effect at run time: view resolution is done by ViewLocationFormats and AreaViewLocationFormats
on JsxCoreOptions, and the two are not read from each other. Changing where views are found in
Program.cs means setting the matching property here as well, or the application will resolve views
the IDE says do not exist.
Packages come from package.json, not the project file. Everything in dependencies is served to
the browser and copied into the publish output; devDependencies are build-time only. See
npm packages for importing them and
package management for installing them.
| Property |
Default |
Purpose |
JsxCoreShowNpmPackagesInIde |
true |
Show installed packages in the project tree |
JsxCoreIdePackageFolder |
package.json |
Virtual folder they appear under, shadowing the manifest |
Not configured through the project file. Installed separately and run by hand:
dotnet tool install -g JsxCore.Npm
dotnet npm add marked --version ^12
| Command |
Purpose |
add, install, i |
Resolve and install a package, recording it in package.json |
remove, rm, un, uninstall |
Drop it, delete it, and re-resolve the rest |
list, ls |
What is declared, and whether it is installed |
restore |
Install what the lock file pins, resolving package.json if there is none |
ci |
Install what the lock file pins, failing if there is no lock file |
init |
Create a package.json |
| Option |
Purpose |
--version <RANGE>, -v |
Version range to add. Defaults to the latest release |
--dev, -D, --save-dev |
Add to devDependencies |
--project <PATH>, --prefix |
Directory or project file to act on. Defaults to the current directory |
--registry <URL> |
Registry to resolve from |
Full reference in package management.
| Code |
Severity |
Meaning |
JSX0001 |
Warning |
The TypeScript compiler was not found; compilation deferred to startup |
JSX0002 |
Error |
TypeScript reported errors and JsxCoreTypeChecking is error |
JSX0003 |
Warning |
TypeScript reported errors and JsxCoreTypeChecking is not error |
JSX0004 |
Warning |
Packages in package.json could not be installed |
JSX0005 |
Error |
Packages are missing and JsxCoreAutoInstallDependencies is false |
JSX0006 |
Warning |
The build tool could not be found, so views were not compiled |
JSX0007 |
Error |
JsxCoreFramework names a framework JsxCore does not know |
| Type |
Thrown when |
JsxCoreEnvironmentException |
Something needed is missing at startup: the toolchain, the views directory, a writable working directory, or compiled output when the application is serving precompiled views |
JsxCompilationException |
Compilation failed and TypeChecking is Error |
JsxViewNotFoundException |
A view could not be located; carries every path probed |
JsxRenderException |
Server-side rendering threw; carries the JavaScript stack trace |
JsxCoreException |
Base type for all of the above |