JS with Types Start

jsconfig.json option

allowArbitraryExtensions

  • Default false
  • Since TypeScript 5.0

Browsers and bundlers can import files that are not JavaScript: CSS module scripts, JSON, SVG and more. TypeScript cannot read those files, but it can read a declaration file that describes one. For ./theme.css, that file is named theme.d.css.ts, and allowArbitraryExtensions is the option that lets TypeScript use it.

Without the option, TypeScript finds the declaration file and still refuses the import, with TS6263. The option arrived with TypeScript 5.0.

At a glance

Write "allowArbitraryExtensions": true when you import CSS, SVG or other non-JavaScript files and write a declaration file for each
On the command line --allowArbitraryExtensions
Type boolean
Default in TypeScript 5.9 false
TypeScript's description Enable importing files with any extension, provided a declaration file is present.

The description is quoted from TypeScript's own option list (Apache-2.0); see the notices.

Examples

main.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: main.js(2,19): error TS6263: Module './theme.css' was resolved to '/project/theme.d.css.ts', but '--allowArbitraryExtensions' is not set. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. main.js(2,19): error TS6263: Module './theme.css' was resolved to '/project/theme.d.css.ts', but '--allowArbitraryExtensions' is not set. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. main.js(2,19): error TS6263: Module './theme.css' was resolved to '/project/theme.d.css.ts', but '--allowArbitraryExtensions' is not set. checked 21 October 2026 
import sheet from "./theme.css" with { type: "css" };error TS6263: Module './theme.css' was resolved to '/project/theme.d.css.ts', but '--allowArbitraryExtensions' is not set.

document.adoptedStyleSheets = [sheet];
A CSS import with a declaration file, without allowArbitraryExtensions.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": [],
    "lib": [
      "es2022",
      "dom"
    ]
  },
  "include": [
    "*.js"
  ]
}
main.js TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
import sheet from "./theme.css" with { type: "css" };

document.adoptedStyleSheets = [sheet];
The same import with allowArbitraryExtensions on.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": [],
    "lib": [
      "es2022",
      "dom"
    ],
    "allowArbitraryExtensions": true
  },
  "include": [
    "*.js"
  ]
}

Naming the declaration file

Put .d before the file's own extension and .ts after it: theme.css → theme.d.css.ts, logo.svg → logo.d.svg.ts. The file describes what the import gives you; for a CSS module script that is one CSSStyleSheet as the default export.

CSS module scripts in the browser

The examples use a CSS module script, a web platform feature: import sheet from "./theme.css" with { type: "css" } gives you a CSSStyleSheet to adopt into the document or a shadow root. Browser support is still uneven, so check MDN before relying on it without a bundler.

One declaration for every file of a kind

The other way to type such imports needs no option: a .d.ts file with declare module "*.css" { … } covers every CSS import at once. Use it when all imports of a kind look the same; use per-file declarations with allowArbitraryExtensions when each file exports something different (CSS modules with class names, for example).

Gotchas

  • An import that binds nothing, such as import "./theme.css", is not checked at all unless noUncheckedSideEffectImports is on.
  • Declaration files you write are skipped by skipLibCheck, the jsconfig.json default, so a mistake in theme.d.css.ts goes unreported.

  • jsconfig.json option

    noUncheckedSideEffectImports

    noUncheckedSideEffectImports reports an import that binds nothing, like import "./polyfills.js", when its file is missing. On by default from TypeScript 6.0.

  • jsconfig.json option

    skipLibCheck

    skipLibCheck skips checking every .d.ts file, your own included. A jsconfig.json turns it on by default, which can hide a typo in a .d.ts you wrote.

  • jsconfig.json option

    resolveJsonModule

    resolveJsonModule lets you import .json files and types their contents. nodenext and bundler turn it on; ES modules still need the json import attribute.

Sources

Last reviewed 20 October 2026.