critical-script

English | 한국어

critical-script is a Vite plugin that turns TypeScript code into an inline <script> tag embedded in prerendered HTML, so that critical work runs before the main JavaScript bundle is loaded.

• Importing a module with ?as-critical-script produces a React component, and the inline script is embedded when that component is rendered to HTML at build time.
• Write it in TypeScript and it is type-checked at compile time. esbuild compiles and minifies the result, keeping the inline script as small as possible.
• It is built for work whose value depends on timing, such as API prefetching, resource preloading, webview native bridges, and LCP optimization.
• The outputSizeLimit option, 8192 bytes by default, caps the inline script at build time and fails the build when the limit is exceeded.
• It works with Vite-based React frameworks that prerender HTML, including react-router in framework mode and @tanstack/react-start.
• It is used in production on major Baemin webview screens, where this API prefetch pattern cut LCP by 30~40% against the previous implementation.

Installation

npm install -D @woowabros/vite-plugin-critical-script
# or
yarn add -D @woowabros/vite-plugin-critical-script
# or
pnpm add -D @woowabros/vite-plugin-critical-script

Example

// home.critical.ts
performance.mark('critical-start')
window.__home = fetch('/api/home').then((r) => r.json())

// home.tsx
import CriticalScript from './home.critical?as-critical-script'

export default function Home() {
  return (
    <>
      <CriticalScript />
      <Page />
    </>
  )
}

<!-- built HTML -->
<script data-size="98">(()=>{performance.mark("critical-start");window.__home=fetch("/api/home").then(e=>e.json());})();</script>

Documentation

The full documentation, including a benchmark you can run in your browser, is published at https://woowabros.github.io/critical-script.

Contributors

We welcome contributions from everyone in the community. Read our Contributing Guide to familiarize yourself with the development process, how to suggest bug fixes and improvements, and the steps for building and testing your changes.

License

MIT © Woowabros. See LICENSE for details.