Open History to see the last commit
1---
2id: vite
3title: Vite
4---
5
6The Vite build setup is the culmination of several attempts to dual publish ESM and CJS for TanStack projects, while preserving compatibility with all Typescript module resolution options.
7
8## Do I Need This?
9
10ES Modules (ESM) is the standard for writing JavaScript modules. However, due to the historical dependency on CommonJS (CJS), many ecosystem tools and projects were initially incompatible with ESM. It is becoming exceedingly rare for this to be the case, and I would urge you to consider whether it is necessary to distribute CJS code at all. Sindre Sorhus has a good summary on this issue [here](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
11
12## Setup
13
14The build config is quite opinionated, as it is designed to work with our internal libraries. If you follow the below instructions, it _may_ work for your library too!
15
16### package.json
17
18- Ensure `"type": "module"` is set.
19- Ensure you have [Vite](https://www.npmjs.com/package/vite) installed. Installing [Publint](https://www.npmjs.com/package/publint) is also recommended.
20- Change your build script to `"build": "vite build && publint --strict"`
21- Ensure you have an `"exports"` field. We use this, but you might have different requirements:
22
23```json
24{
25 "exports": {
26 ".": {
27 "import": {
28 "types": "./dist/esm/index.d.ts",
29 "default": "./dist/esm/index.js"
30 },
31 "require": {
32 "types": "./dist/cjs/index.d.cts",
33 "default": "./dist/cjs/index.cjs"
34 }
35 },
36 "./package.json": "./package.json"
37 }
38}
39```
40
41### tsconfig.json
42
43- Ensure your `"include"` field includes `"vite.config.ts"`.
44- Set `"moduleResolution"` to `"bundler"`.
45
46### vite.config.ts
47
48- Import `mergeConfig` and `tanstackViteConfig`.
49- Merge your custom config first, followed by `tanstackViteConfig`.
50- Please avoid modifying `build` in your custom config.
51- See an example below:
52
53```ts
54import { defineConfig, mergeConfig } from 'vite'
55
56import { tanstackViteConfig } from '@tanstack/config/vite'
57// OR
58import { tanstackViteConfig } from '@tanstack/vite-config'
59
60const config = defineConfig({
61 // Framework plugins, vitest config, etc.
62})
63
64export default mergeConfig(
65 config,
66 tanstackViteConfig({
67 entry: './src/index.ts',
68 srcDir: './src',
69 }),
70)
71```
72
73## Frameworks
74
75While this config _will_ work with most frameworks with a Vite adapter, it doesn't mean you _should_ use it for all frameworks, as many have their own build tools which are optimised for their ecosystem. When a framework-specific build tool exists, this should be preferred.
76
77| Framework | Recommendation |
78| --------- | -------------------------------------------------------------------------------------------------- |
79| Angular | [ng-packagr](https://www.npmjs.com/package/ng-packagr) (official tool) |
80| React | [@tanstack/config](https://www.npmjs.com/package/@tanstack/config) (only if you need dual ESM/CJS) |
81| Solid | [tsc](https://www.npmjs.com/package/typescript) (preserves JSX, necessary for SSR) |
82| Svelte | [@sveltejs/package](https://www.npmjs.com/package/@sveltejs/package) (official tool) |
83| Vue | [@tanstack/config](https://www.npmjs.com/package/@tanstack/config) (only if you need dual ESM/CJS) |