On this page
Configuring JSX in Deno
Deno has built-in support for JSX in both .jsx
files and .tsx
files. JSX in
Deno can be handy for server-side rendering or generating code for consumption
in a browser.
Default configuration Jump to heading
The Deno CLI has a default configuration for JSX that is different than the
defaults for tsc
. Effectively Deno uses the following
TypeScript compiler
options by default:
{
"compilerOptions": {
"jsx": "react",
"jsxFactory": "React.createElement",
"jsxFragmentFactory": "React.Fragment"
}
}
JSX import source Jump to heading
In React 17, the React team added what they called the new JSX transforms. This enhanced and modernized the API for JSX transforms as well as provided a mechanism to automatically import a JSX library into a module, instead of having to explicitly import it or make it part of the global scope. Generally this makes it easier to use JSX in your application.
As of Deno 1.16, initial support for these transforms was added. Deno supports both the JSX import source pragma as well as configuring a JSX import source in a configuration file.
JSX runtime Jump to heading
When using the automatic transforms, Deno will try to import a JSX runtime
module that is expected to conform to the new JSX API and is located at either
jsx-runtime
or jsx-dev-runtime
. For example if a JSX import source is
configured to react
, then the emitted code will add this to the emitted file:
import { jsx as _jsx } from "react/jsx-runtime";
Deno generally works off explicit specifiers, which means it will not try any
other specifier at runtime than the one that is emitted. Which means to
successfully load the JSX runtime, "react/jsx-runtime"
would need to resolve
to a module. Saying that, Deno supports remote modules, and most CDNs resolve
the specifier easily.
For example, if you wanted to use Preact from the
esm.sh CDN, you would use https://esm.sh/preact
as the JSX
import source, and esm.sh will resolve https://esm.sh/preact/jsx-runtime
as a
module, including providing a header in the response that tells Deno where to
find the type definitions for Preact.
Using the JSX import source pragma Jump to heading
Whether you have a JSX import source configured for your project, or if you are
using the default "legacy" configuration, you can add the JSX import source
pragma to a .jsx
or .tsx
module, and Deno will respect it.
The @jsxImportSource
pragma needs to be in the leading comments of the module.
For example to use Preact from esm.sh, you would do something like this:
/** @jsxImportSource https://esm.sh/preact */
export function App() {
return (
<div>
<h1>Hello, world!</h1>
</div>
);
}
Using JSX import source in a configuration file Jump to heading
If you want to configure a JSX import source for a whole project, so you don't
need to insert the pragma on each module, you can use the "compilerOptions"
in
a configuration file to specify
this. For example if you were using Preact as your JSX library from esm.sh, you
would configure the following, in the configuration file:
{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "https://esm.sh/preact"
}
}
Using an import map Jump to heading
In situations where the import source plus /jsx-runtime
or /jsx-dev-runtime
is not resolvable to the correct module, an import map can be used to instruct
Deno where to find the module. An import map can also be used to make the import
source "cleaner". For example, if you wanted to use Preact from
(esm.sh)[https://esm.sh/] and include all the type information, you could setup
an import map like this:
{
"imports": {
"preact/jsx-runtime": "https://esm.sh/preact/jsx-runtime?dts",
"preact/jsx-dev-runtime": "https://esm.sh/preact/jsx-dev-runtime?dts"
}
}
And then you could use the following pragma:
/** @jsxImportSource preact */
Or you could configure it in the compiler options:
{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "preact"
}
}
You would then need to pass the --import-map
option on the command line (along
with the --config
option is using a config file) or set the deno.importMap
option (and deno.config
option) in your IDE.
jsxImportSourceTypes
Jump to heading
In certain cases, a library may not provide types. To specify the types, you can
use the @jsxImportSourceTypes
pragma:
/** @jsxImportSource npm:react@^18.3 */
/** @jsxImportSourceTypes npm:@types/react@^18.3 */
export function Hello() {
return <div>Hello!</div>;
}
Or specify via the jsxImportSourceTypes
compiler option in a deno.json:
{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "npm:react@^18.3",
"jsxImportSourceTypes": "npm:@types/react@^18.3"
}
}
Current limitations Jump to heading
There are two current limitations of the support of the JSX import source:
- A JSX module that does not have any imports or exports is not transpiled
properly when type checking (see:
microsoft/TypeScript#46723).
Errors will be seen at runtime about
_jsx
not being defined. To work around the issue, addexport {}
to the file or use the--no-check
flag which will cause the module to be emitted properly. - Using
"jsx-reactdev"
compiler option is not supported with--no-emit
/bundling/compiling (see: swc-project/swc#2656). Various runtime errors will occur about not being able to loadjsx-runtime
modules. To work around the issue, use the"jsx-react"
compiler option instead, or don't use--no-emit
, bundling or compiling.