Every import a view can write, and what each one resolves to.
Two kinds are ordinary JavaScript: your own files, and npm packages. The rest are JsxCore's, and all use a scheme rather than a package name, because nothing behind them comes from npm:
| Written | Resolves to |
|---|---|
"./Card.tsx", "@/Shared/Card.tsx" |
another view or component of yours |
"marked", "preact/hooks" |
an npm package, or the framework |
"dotnet:types", "dotnet:types/MyApp/Models" |
types generated from your .NET code |
"dotnet:globals", "dotnet:rendering" |
the .NET objects you registered, and the view contract |
"dotnet:rendering/head" |
the <Head> component |
"@jsxcore/client" |
mountView, from whichever framework the project builds against |
"/images/logo.svg" |
a static file of yours, as the URL it is served from |
Plain ESM, with the real extension:
import { Card, Nav } from "../Shared/Layout.tsx";
import { formatMoney } from "./money.ts";TypeScript rewrites the extension on the way out, so ./Card.tsx is emitted as ./Card.js and the
browser fetches that. Writing ./Card without an extension does not work: the compiler leaves it
alone, and the browser will not probe for a file that resolves it.
Components can live anywhere under the views directory. There is no registration step and no barrel file; an export is enough. Only a view, meaning a module returned from an endpoint, needs a default export.
An import that resolves outside the views directory is refused.
@/ is the views directory, so a deep component can reach a shared one without counting ../:
import { Card } from "@/Shared/Card.tsx";The same alias every Next.js and Vite template scaffolds, generated for you in both the compiler
configuration and the editor one. Aliases of your own work too: add them to
options.CompilerOptions["paths"] and they merge over the generated ones rather than replacing
them. Any alias landing inside the views directory is rewritten to a relative path when the view
compiles, which is what makes it resolve in a browser and not only in an editor.
Bare specifiers, exactly as anywhere else:
import { marked } from "marked";
import { nanoid } from "nanoid/non-secure";JsxCore follows the graph from your compiled views, resolves every bare specifier, and generates an import map so the browser can do the same. Nothing is bundled and there is no configuration to write. See npm packages for what resolves, and for the CommonJS story: a package published as CommonJS is wrapped automatically, but a default import is the reliable form.
import pkg from "some-commonjs-package";
const { thing } = pkg;devDependencies are deliberately not served to the browser, because they are not in the publish
output. Importing one from a client-rendered view logs a warning naming the package rather than
failing later in production.
The framework is imported like any other package:
import { useState } from "preact/hooks"; // Preact, the default
import { useState } from "react"; // React modeIn Preact mode react and react-dom are mapped onto preact/compat, so components written
against React resolve unchanged. See Runtimes.
dotnet: is the .NET side of the application: types, globals and rendering. These type
imports are erased during compilation and never reach the browser.
The usual form, and the one that reads like .NET:
import type { Product } from "dotnet:types/MyApp/Models";
import type { Money } from "dotnet:types/MyApp/Models/Pricing";The path after dotnet:types is the .NET namespace, with / for .. Nested namespaces nest.
No assembly appears anywhere. MyApp.Models.Product is dotnet:types/MyApp/Models whether it
was declared in the web project or in a contracts project that one references, which is how
using MyApp.Models behaves in C# too. Moving a type between projects does not move the specifier
that reaches it.
import type Types from "dotnet:types";
function show(product: Types.MyApp.Models.Product) { /* ... */ }Everything is declared here, and the namespace modules above are facades aliasing it rather than second declarations, so the two forms name the same type and are assignable to each other.
See Model types for what gets exported and how to control it.
Each object registered with options.Globals is a named export, typed from the C# it was
registered as:
import { Inventory } from "dotnet:globals";
const total = Inventory.getTotalValue(); // checked against your C# methodUnlike the type imports above, this one is sent to the browser, so that a view rendering on both
sides can import it. Using a global on the client throws with an explanatory message; guard it with
isServerRender() if a view runs in both modes.
dotnet is exported from the same module and reaches any global by name. It is untyped, and is
what to use for a global registered under a name that is not a valid identifier:
import { dotnet } from "dotnet:globals";
const service = dotnet["my service"];Until the application has run once the build cannot know what is registered, so these imports type
as any and sharpen after a run. See .NET interop.
Static files live in wwwroot, served by UseStaticFiles(). Import one by the URL it is served
from:
import logo from "/images/logo.svg";
export default function Header() {
return <img src={logo} alt="Contoso" />;
}The specifier and the URL are the same string, which is the point: wwwroot/images/logo.svg is
served at /images/logo.svg, so that is what you write. It resolves to that URL, typed string.
Nothing is copied or versioned. The point is the check: a typo becomes a compile error instead of a
broken image in production. <img src="/images/logo.svg" /> by hand still works.
Any web asset extension resolves: images, fonts, video, .pdf.
For everything but stylesheets, the path has to start at the root. ./logo.svg beside a view
names nothing JsxCore serves, because views are a source tree. It type checks anyway, since the
declarations behind this are *.svg wildcards and TypeScript rejects a pattern beginning with a
slash, so the build reports it by name instead. A rooted path naming a file the web root does not
hold is reported the same way.
Stylesheets are the exception, because JsxCore processes those. See below.
Three places a stylesheet can come from, and the spelling says which:
import "/css/site.css"; // your web root, served by UseStaticFiles
import "./card.css"; // beside the component
import "some-widget/styles.css"; // an npm package's own styles
import styles from "./Card.module.css"; // a CSS module, with scoped class namesThe first three bind nothing and are answered with a <link> in the document. A *.module.css
binds the scoped class names, so styles.card is what goes in the markup.
See Styling for what each is for, how ordering is decided, and Tailwind.
import { isServerRender } from "dotnet:rendering";
import type { ViewProps, HeadDescriptor } from "dotnet:rendering";isServerRender() says which pass is running. ViewProps<TModel> is what every view is handed,
and HeadDescriptor is what a head export may return.
One sub-path, for the component that sets document head tags from inside the tree:
import Head from "dotnet:rendering/head";
<Head><title>Products</title></Head>See Writing views for what it does and when to prefer the
head export.
Ordinary import() works, which is how to keep a browser-only package out of the server pass:
import { isServerRender } from "dotnet:rendering";
if (!isServerRender()) {
const { default: chart } = await import("chart.js");
}| Import | Erased at compile time | Needs an import map entry |
|---|---|---|
import type ... from "dotnet:types" |
Yes | No |
import { Inventory } from "dotnet:globals" |
No | Yes |
import { isServerRender } from "dotnet:rendering" |
No | Yes |
import { marked } from "marked" |
No | Yes |
import { Card } from "./Card.tsx" |
No | No: a relative URL |
import logo from "/images/logo.svg" |
No | No: rewritten to a relative URL |
import Head from "dotnet:rendering/head" |
No | Yes |
The entries are generated for you. options.ImportMap adds your own, and wins over the generated
ones, which is how to point a package at a CDN. See
Extensibility.
- Writing views: the view contract,
head, hooks, the JSX dialect - Model types: what
dotnet:typescontains and how to control it - .NET interop: registering the objects behind
dotnet:globals - npm packages: what resolves from
node_modules, on both sides