Skip to content

Commit 74e6f3d

Browse files
patak-devpatak-dev
authored
docs: static deployment guide (#2339)
1 parent b65bc61 commit 74e6f3d

File tree

4 files changed

+273
-1
lines changed

4 files changed

+273
-1
lines changed

‎docs/.vitepress/config.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,10 @@ module.exports = {
9393
text: 'Building for Production',
9494
link: '/guide/build'
9595
},
96+
{
97+
text: 'Deploying a Static Site',
98+
link: '/guide/static-deploy'
99+
},
96100
{
97101
text: 'Env Variables and Modes',
98102
link: '/guide/env-and-mode'

‎docs/guide/build.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Building for Production
22

3-
When it is time to deploy your app for production, simply run the `vite build` command. By default, it uses `<root>/index.html` as the build entry point, and produces an application bundle that is suitable to be served over a static hosting service.
3+
When it is time to deploy your app for production, simply run the `vite build` command. By default, it uses `<root>/index.html` as the build entry point, and produces an application bundle that is suitable to be served over a static hosting service. Check out the [Deploying a Static Site](./static-deploy) for guides about popular services.
44

55
## Browser Compatibility
66

‎docs/guide/static-deploy.md

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
# Deploying a Static Site
2+
3+
The following guides are based on some shared assumptions:
4+
5+
- You are using the default build output location (`dist`). This location [can be changed using `build.outDir`](https://vitejs.dev/config/#build-outdir), and you can extrapolate instructions from these guides in that case.
6+
- Vite is installed as a local dev dependency in your project, and you have setup the following npm scripts:
7+
- You are using npm. You can use equivalent commands to run the scripts if you are using Yarn or other package managers.
8+
9+
```json
10+
{
11+
"scripts": {
12+
"build": "vite build",
13+
"preview": "vite preview"
14+
}
15+
}
16+
```
17+
18+
It is important to note that `vite preview` is intended for previewing the build locally and not meant as a production server.
19+
20+
::: tip NOTE
21+
These guides provide instructions for performing a static deployment of your Vite site. Vite also has experimental support for Server Side Rendering. SSR refers to front-end frameworks that support running the same application in Node.js, pre-rendering it to HTML, and finally hydrating it on the client. Check out the [SSR Guide](./ssr) to learn about this feature. On the other hand, if you are looking for integration with traditional server-side frameworks, check out the [Backend Integration guide](./backend-integration) instead.
22+
:::
23+
24+
## Building The App
25+
26+
You may run `npm run build` command to build the app.
27+
28+
```bash
29+
$ npm run build
30+
```
31+
32+
By default, the build output will be placed at `dist`. You may deploy this `dist` folder to any of your preferred platforms.
33+
34+
### Testing The App Locally
35+
36+
Once you've built the app, you may test it locally by running `npm run preview` command.
37+
38+
```bash
39+
$ npm run build
40+
$ npm run preview
41+
```
42+
43+
The `preview` command will boot up local static web server that serves the files from `dist` at http://localhost:5000. It's an easy way to check if the production build looks OK in your local environment.
44+
45+
You may configure the port of the server py passing `--port` flag as an argument.
46+
47+
```json
48+
{
49+
"scripts": {
50+
"preview": "vite preview --port 8080"
51+
}
52+
}
53+
```
54+
55+
Now the `preview` method will launch the server at http://localhost:8080.
56+
57+
## GitHub Pages
58+
59+
1. Set the correct `base` in `vite.config.js`.
60+
61+
If you are deploying to `https://<USERNAME>.github.io/`, you can omit `base` as it defaults to `'/'`.
62+
63+
If you are deploying to `https://<USERNAME>.github.io/<REPO>/`, for example your repository is at `https://github.com/<USERNAME>/<REPO>`, then set `base` to `'/<REPO>/'`.
64+
65+
2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately), and run it to deploy:
66+
67+
```bash{13,20,23}
68+
#!/usr/bin/env sh
69+
70+
# abort on errors
71+
set -e
72+
73+
# build
74+
npm run build
75+
76+
# navigate into the build output directory
77+
cd dist
78+
79+
# if you are deploying to a custom domain
80+
# echo 'www.example.com' > CNAME
81+
82+
git init
83+
git add -A
84+
git commit -m 'deploy'
85+
86+
# if you are deploying to https://<USERNAME>.github.io
87+
# git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master
88+
89+
# if you are deploying to https://<USERNAME>.github.io/<REPO>
90+
# git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages
91+
92+
cd -
93+
```
94+
95+
::: tip
96+
You can also run the above script in your CI setup to enable automatic deployment on each push.
97+
:::
98+
99+
### GitHub Pages and Travis CI
100+
101+
1. Set the correct `base` in `vite.config.js`.
102+
103+
If you are deploying to `https://<USERNAME or GROUP>.github.io/`, you can omit `base` as it defaults to `'/'`.
104+
105+
If you are deploying to `https://<USERNAME or GROUP>.github.io/<REPO>/`, for example your repository is at `https://github.com/<USERNAME>/<REPO>`, then set `base` to `'/<REPO>/'`.
106+
107+
2. Create a file named `.travis.yml` in the root of your project.
108+
109+
3. Run `npm install` locally and commit the generated lockfile (`package-lock.json`).
110+
111+
4. Use the GitHub Pages deploy provider template, and follow the [Travis CI documentation](https://docs.travis-ci.com/user/deployment/pages/).
112+
113+
```yaml
114+
language: node_js
115+
node_js:
116+
- lts/*
117+
install:
118+
- npm ci
119+
script:
120+
- npm run build
121+
deploy:
122+
provider: pages
123+
skip_cleanup: true
124+
local_dir: dist
125+
# A token generated on GitHub allowing Travis to push code on you repository.
126+
# Set in the Travis settings page of your repository, as a secure variable.
127+
github_token: $GITHUB_TOKEN
128+
keep_history: true
129+
on:
130+
branch: master
131+
```
132+
133+
## GitLab Pages and GitLab CI
134+
135+
1. Set the correct `base` in `vite.config.js`.
136+
137+
If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/`, you can omit `base` as it defaults to `'/'`.
138+
139+
If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/<REPO>/`, for example your repository is at `https://gitlab.com/<USERNAME>/<REPO>`, then set `base` to `'/<REPO>/'`.
140+
141+
2. Set `build.outDir` in `vite.config.js` to `public`.
142+
143+
3. Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:
144+
145+
```yaml
146+
image: node:10.22.0
147+
pages:
148+
cache:
149+
paths:
150+
- node_modules/
151+
script:
152+
- npm install
153+
- npm run build
154+
artifacts:
155+
paths:
156+
- public
157+
only:
158+
- master
159+
```
160+
161+
## Netlify
162+
163+
1. On [Netlify](https://netlify.com), setup up a new project from GitHub with the following settings:
164+
165+
- **Build Command:** `vite build` or `npm run build`
166+
- **Publish directory:** `dist`
167+
168+
2. Hit the deploy button.
169+
170+
## Google Firebase
171+
172+
1. Make sure you have [firebase-tools](https://www.npmjs.com/package/firebase-tools) installed.
173+
174+
2. Create `firebase.json` and `.firebaserc` at the root of your project with the following content:
175+
176+
`firebase.json`:
177+
178+
```json
179+
{
180+
"hosting": {
181+
"public": "dist",
182+
"ignore": []
183+
}
184+
}
185+
```
186+
187+
`.firebaserc`:
188+
189+
```js
190+
{
191+
"projects": {
192+
"default": "<YOUR_FIREBASE_ID>"
193+
}
194+
}
195+
```
196+
197+
3. After running `npm run build`, deploy using the command `firebase deploy`.
198+
199+
## Surge
200+
201+
1. First install [surge](https://www.npmjs.com/package/surge), if you haven’t already.
202+
203+
2. Run `npm run build`.
204+
205+
3. Deploy to surge by typing `surge dist`.
206+
207+
You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-domain) by adding `surge dist yourdomain.com`.
208+
209+
## Heroku
210+
211+
1. Install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).
212+
213+
2. Create a Heroku account by [signing up](https://signup.heroku.com).
214+
215+
3. Run `heroku login` and fill in your Heroku credentials:
216+
217+
```bash
218+
$ heroku login
219+
```
220+
221+
4. Create a file called `static.json` in the root of your project with the below content:
222+
223+
`static.json`:
224+
225+
```json
226+
{
227+
"root": "./dist"
228+
}
229+
```
230+
231+
This is the configuration of your site; read more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static).
232+
233+
5. Set up your Heroku git remote:
234+
235+
```bash
236+
# version change
237+
$ git init
238+
$ git add .
239+
$ git commit -m "My site ready for deployment."
240+
241+
# creates a new app with a specified name
242+
$ heroku apps:create example
243+
244+
# set buildpack for static sites
245+
$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git
246+
```
247+
248+
6. Deploy your site:
249+
250+
```bash
251+
# publish site
252+
$ git push heroku master
253+
254+
# opens a browser to view the Dashboard version of Heroku CI
255+
$ heroku open
256+
```
257+
258+
## Vercel
259+
260+
To deploy your Vite app with a [Vercel for Git](https://vercel.com/docs/git), make sure it has been pushed to a Git repository.
261+
262+
Go to https://vercel.com/import/git and import the project into Vercel using your Git of choice (GitHub, GitLab or BitBucket). Follow the wizard to select the project root with the project's `package.json` and override the build step using `npm run build` and the output dir to be `./dist`
263+
264+
![Override Vercel Configuration](../images/vercel-configuration.png)
265+
266+
After your project has been imported, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (commonly "main") will result in a Production Deployment.
267+
268+
Once deployed, you will get a URL to see your app live, such as the following: https://vite.vercel.app

‎docs/images/vercel-configuration.png

35 KB
Loading

0 commit comments

Comments
 (0)