Skip to content

Commit 0da1cfe

Browse files
mwood23mwood23
authored
adds vite plugin docs (#21)
<!-- If this pull request closes an issue, please mention the issue number below --> Closes # <!-- Issue # here --> ## 💸 TL;DR <!-- What's the three sentence summary of purpose of the PR --> Adds vite plugin docs to address questions we received in the Discord yesterday! ## 📜 Details [Design Doc](<!-- insert Google Doc link here if applicable -->) <img width="2816" height="1524" alt="CleanShot 2026-01-15 at 11 17 29@2x" src="https://github.com/user-attachments/assets/376ef091-9e48-40f8-bb6a-c57e26989fd9" /> [Jira](<!-- insert Jira link if applicable -->) <!-- Add additional details required for the PR: breaking changes, screenshots, external dependency changes --> ## 🧪 Testing Steps / Validation <!-- add details on how this PR has been tested, include reproductions and screenshots where applicable --> ## ✅ Checks <!-- Make sure your pr passes the CI checks and do check the following fields as needed - --> - [ ] CI tests (if present) are passing - [ ] Adheres to code style for repo - [ ] Contributor License Agreement (CLA) completed if not a Reddit employee
1 parent f101a07 commit 0da1cfe

File tree

3 files changed

+263
-7
lines changed

3 files changed

+263
-7
lines changed

‎docs/guides/tools/vite.mdx‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
id: vite
3+
title: Vite Plugin
4+
sidebar_label: Vite Plugin
5+
---
6+
7+
# Build with the Devvit Vite plugin
8+
9+
::::warning Experimental
10+
The Devvit Vite plugin is experimental and subject to breaking changes.
11+
::::
12+
13+
The Devvit [Vite](https://vite.dev/) plugin is a 100% optional plugin for Devvit Web that unifies your client and server builds into a single command using [Vite's Environment API](https://vite.dev/guide/api-environment).
14+
15+
Features:
16+
17+
- Unified build command for client and server
18+
- Automatic entrypoint bundling based on your `devvit.json` configuration
19+
- Optimized configuration for building your code for Devvit
20+
21+
The plugin is **completely optional**. You can use Vite without it, or swap in Webpack, esbuild, or any other bundler you prefer.
22+
23+
You can see a full template using it here: https://github.com/reddit/devvit-template-vibe-coding/blob/main/vite.config.ts
24+
25+
## Quick start
26+
27+
Add the plugin to your `vite.config.ts` alongside any UI tooling you already use:
28+
29+
```ts
30+
import { defineConfig } from "vite";
31+
import react from "@vitejs/plugin-react";
32+
import tailwind from "@tailwindcss/vite";
33+
import { devvit } from "@devvit/start/vite";
34+
35+
export default defineConfig({
36+
plugins: [
37+
react(),
38+
tailwind(),
39+
// Make sure to add the Devvit plugin last!
40+
devvit(),
41+
],
42+
});
43+
```
44+
45+
## What the plugin expects
46+
47+
The plugin uses your `devvit.json` as the source of truth for client entry points. Make sure you have at least one entrypoint defined:
48+
49+
```json
50+
{
51+
"post": {
52+
"dir": "dist/client",
53+
"entrypoints": {
54+
"default": {
55+
"inline": true,
56+
"entry": "src/splash.html"
57+
}
58+
}
59+
}
60+
}
61+
```
62+
63+
For the server build, the plugin looks for one of these files:
64+
65+
- `src/server/index.ts`
66+
- `src/api/index.ts`
67+
68+
If neither file exists, the build fails with a clear error message.
69+
70+
## What it builds
71+
72+
Out of the box, the plugin configures two environments:
73+
74+
- **Client build** outputs to `dist/client` and uses the entry points from `devvit.json`.
75+
- **Server build** outputs to `dist/server` as `index.cjs`
76+
77+
> Note that Devvit requires a single CJS bundle to run the server code. Please do not mark server dependencies as `external` as it will break your server build. This may change in the future!
78+
79+
## Customize the build
80+
81+
The plugin accepts a small options object that lets you tweak both environments without redoing the whole config. Each option is merged into the generated Vite environment config.
82+
83+
```ts
84+
type DevvitPluginOptions = {
85+
client?: EnvironmentOptions;
86+
server?: EnvironmentOptions;
87+
logLevel?: "info" | "warn" | "error" | "silent";
88+
verbose?: boolean;
89+
};
90+
```
91+
92+
For example, if you want to disable sourcemaps for the client build:
93+
94+
```ts
95+
import { defineConfig } from "vite";
96+
import { devvit } from "@devvit/start/vite";
97+
98+
export default defineConfig({
99+
plugins: [
100+
devvit({
101+
client: {
102+
build: {
103+
sourcemap: false,
104+
},
105+
},
106+
}),
107+
],
108+
});
109+
```
110+
111+
Any customization you make is automatically merged into the generated environment config so don't worry about spreading our defaults across your config changes.
112+
113+
## Sharing code between client and server
114+
115+
If you need to share code between client and server, keep it outside of `src/server` and `src/api`. Treat those folders as server-only. Put shared modules in a neutral folder (for example `src/shared`) and import them from both environments.
116+
117+
```text
118+
src/
119+
server/
120+
index.ts # server entry
121+
client/
122+
main.tsx # client entry
123+
shared/
124+
formatScore.ts # safe to import from client + server
125+
```
126+
127+
## Limitations and gotchas
128+
129+
- **Build-only:** The plugin only supports `vite build`. There is no support for `vite dev` or Hot Module Replacement (HMR) at this time. This is because `devvit playtest` works by uploading your build to our servers and running it on Reddit.com. Instead, use `vite build --watch` as your dev command.
130+
- **Entry points are required:** Building server apps only is not yet supported. If you'd like to request this feature, please [open an issue](https://github.com/reddit/devvit/issues/new).

‎versioned_docs/version-0.12/guides/tools/vite.mdx‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
id: vite
3+
title: Vite Plugin
4+
sidebar_label: Vite Plugin
5+
---
6+
7+
# Build with the Devvit Vite plugin
8+
9+
::::warning Experimental
10+
The Devvit Vite plugin is experimental and subject to breaking changes.
11+
::::
12+
13+
The Devvit [Vite](https://vite.dev/) plugin is a 100% optional plugin for Devvit Web that unifies your client and server builds into a single command using [Vite's Environment API](https://vite.dev/guide/api-environment).
14+
15+
Features:
16+
17+
- Unified build command for client and server
18+
- Automatic entrypoint bundling based on your `devvit.json` configuration
19+
- Optimized configuration for building your code for Devvit
20+
21+
The plugin is **completely optional**. You can use Vite without it, or swap in Webpack, esbuild, or any other bundler you prefer.
22+
23+
You can see a full template using it here: https://github.com/reddit/devvit-template-vibe-coding/blob/main/vite.config.ts
24+
25+
## Quick start
26+
27+
Add the plugin to your `vite.config.ts` alongside any UI tooling you already use:
28+
29+
```ts
30+
import { defineConfig } from "vite";
31+
import react from "@vitejs/plugin-react";
32+
import tailwind from "@tailwindcss/vite";
33+
import { devvit } from "@devvit/start/vite";
34+
35+
export default defineConfig({
36+
plugins: [
37+
react(),
38+
tailwind(),
39+
// Make sure to add the Devvit plugin last!
40+
devvit(),
41+
],
42+
});
43+
```
44+
45+
## What the plugin expects
46+
47+
The plugin uses your `devvit.json` as the source of truth for client entry points. Make sure you have at least one entrypoint defined:
48+
49+
```json
50+
{
51+
"post": {
52+
"dir": "dist/client",
53+
"entrypoints": {
54+
"default": {
55+
"inline": true,
56+
"entry": "src/splash.html"
57+
}
58+
}
59+
}
60+
}
61+
```
62+
63+
For the server build, the plugin looks for one of these files:
64+
65+
- `src/server/index.ts`
66+
- `src/api/index.ts`
67+
68+
If neither file exists, the build fails with a clear error message.
69+
70+
## What it builds
71+
72+
Out of the box, the plugin configures two environments:
73+
74+
- **Client build** outputs to `dist/client` and uses the entry points from `devvit.json`.
75+
- **Server build** outputs to `dist/server` as `index.cjs`
76+
77+
> Note that Devvit requires a single CJS bundle to run the server code. Please do not mark server dependencies as `external` as it will break your server build. This may change in the future!
78+
79+
## Customize the build
80+
81+
The plugin accepts a small options object that lets you tweak both environments without redoing the whole config. Each option is merged into the generated Vite environment config.
82+
83+
```ts
84+
type DevvitPluginOptions = {
85+
client?: EnvironmentOptions;
86+
server?: EnvironmentOptions;
87+
logLevel?: "info" | "warn" | "error" | "silent";
88+
verbose?: boolean;
89+
};
90+
```
91+
92+
For example, if you want to disable sourcemaps for the client build:
93+
94+
```ts
95+
import { defineConfig } from "vite";
96+
import { devvit } from "@devvit/start/vite";
97+
98+
export default defineConfig({
99+
plugins: [
100+
devvit({
101+
client: {
102+
build: {
103+
sourcemap: false,
104+
},
105+
},
106+
}),
107+
],
108+
});
109+
```
110+
111+
Any customization you make is automatically merged into the generated environment config so don't worry about spreading our defaults across your config changes.
112+
113+
## Sharing code between client and server
114+
115+
If you need to share code between client and server, keep it outside of `src/server` and `src/api`. Treat those folders as server-only. Put shared modules in a neutral folder (for example `src/shared`) and import them from both environments.
116+
117+
```text
118+
src/
119+
server/
120+
index.ts # server entry
121+
client/
122+
main.tsx # client entry
123+
shared/
124+
formatScore.ts # safe to import from client + server
125+
```
126+
127+
## Limitations and gotchas
128+
129+
- **Build-only:** The plugin only supports `vite build`. There is no support for `vite dev` or Hot Module Replacement (HMR) at this time. This is because `devvit playtest` works by uploading your build to our servers and running it on Reddit.com. Instead, use `vite build --watch` as your dev command.
130+
- **Entry points are required:** Building server apps only is not yet supported. If you'd like to request this feature, please [open an issue](https://github.com/reddit/devvit/issues/new).

‎versioned_sidebars/version-0.12-sidebars.json‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -145,10 +145,7 @@
145145
{
146146
"type": "category",
147147
"label": "Automation & Triggers",
148-
"items": [
149-
"capabilities/server/scheduler",
150-
"capabilities/server/triggers"
151-
]
148+
"items": ["capabilities/server/scheduler", "capabilities/server/triggers"]
152149
},
153150
{
154151
"type": "category",
@@ -187,9 +184,7 @@
187184
{
188185
"type": "category",
189186
"label": "Realtime Apps",
190-
"items": [
191-
"capabilities/realtime/overview"
192-
]
187+
"items": ["capabilities/realtime/overview"]
193188
},
194189
{
195190
"type": "category",
@@ -272,6 +267,7 @@
272267
"items": [
273268
"guides/tools/devvit_cli",
274269
"guides/tools/devvit_test",
270+
"guides/tools/vite",
275271
"guides/tools/logs",
276272
"guides/tools/playtest",
277273
"guides/tools/ui_simulator"

0 commit comments

Comments
 (0)