Import queries

Five import queries deliver CSS into a shadow root, and two of them come from this plugin. This page states what each one yields and how it behaves on an edit; the guides linked in the last column show them in use.

Query	Yields	Added by	HMR behaviour	Used on
?css-sheet	a shared CSSStyleSheet	this plugin	swaps in place, no component re-render	?css-sheet
?hmr-url	a stylesheet URL (string)	this plugin	re-renders the component with a busted href	Component styles
?url	an asset URL (string)	Vite	URL is stable, so call devCacheBust()	urlSheet()
?inline	processed CSS text (string)	Vite	re-renders the component	Component styles
?raw	verbatim file text (string)	Vite	re-renders the component	Component styles

Which one to reach for is a delivery tradeoff, and the stylesheets guide works through it.

Ambient types

The two queries this plugin adds ship their declarations in @oddsquad/vite-plugin-lit/client:

declare module '*.css?hmr-url' {
  const href: string;
  export default href;
}

declare module '*.css?css-sheet' {
  const sheet: CSSStyleSheet;
  export default sheet;
}

Pull them in through the types field of your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "types": ["vite/client", "@oddsquad/vite-plugin-lit/client"],
    "experimentalDecorators": true,
    "useDefineForClassFields": false
  },
  "include": ["src"]
}

A triple-slash reference in any .d.ts file does the same job, and leaves the types field alone:

src/vite-env.d.ts

/// <reference types="vite/client" />
/// <reference types="@oddsquad/vite-plugin-lit/client" />

?url, ?inline, and ?raw are typed by vite/client, which a Vite project almost always references already.

`types` replaces, it does not extend

Listing types at all narrows the set of ambient packages TypeScript loads. If you add @oddsquad/vite-plugin-lit/client, keep vite/client and anything else you relied on in the same array.

virtual:lit-plugin/timeline

Custom timeline layers are imported from a virtual module rather than a file path:

import {addTimelineEvent, addTimelineLayer} from 'virtual:lit-plugin/timeline';

Its types ship in the same @oddsquad/vite-plugin-lit/client declarations, so the types entry or the triple-slash reference above already covers it. The full declaration is on the runtime API page, and custom layers puts it to work.

Related

Runtime APIurlSheet(), devCacheBust(), and the timeline exports.

Component stylesWhen to reach for ?hmr-url, ?inline, or ?raw.