Skip to content
Source
Sign inSign up
TanStack/config
Open History to see the last commit

vite.md

83 lines3.3 KB

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
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 }
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 }),
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) |