docs: static deployment guide (#2339)

docs/.vitepress/config.js

@@ -93,6 +93,10 @@ module.exports = {
               text: 'Building for Production',
               link: '/guide/build'
             },
+            {
+              text: 'Deploying a Static Site',
+              link: '/guide/static-deploy'
+            },
             {
               text: 'Env Variables and Modes',
               link: '/guide/env-and-mode'

docs/guide/build.md

@@ -1,6 +1,6 @@
 # Building for Production
 
-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.
+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.
 
 ## Browser Compatibility
 

docs/guide/static-deploy.md

@@ -0,0 +1,268 @@
+# Deploying a Static Site
+
+The following guides are based on some shared assumptions:
+
+- 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.
+- Vite is installed as a local dev dependency in your project, and you have setup the following npm scripts:
+- You are using npm. You can use equivalent commands to run the scripts if you are using Yarn or other package managers.
+
+```json
+{
+  "scripts": {
+    "build": "vite build",
+    "preview": "vite preview"
+  }
+}
+```
+
+It is important to note that `vite preview` is intended for previewing the build locally and not meant as a production server.
+
+::: tip NOTE
+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.
+:::
+
+## Building The App
+
+You may run `npm run build` command to build the app.
+
+```bash
+$ npm run build
+```
+
+By default, the build output will be placed at `dist`. You may deploy this `dist` folder to any of your preferred platforms.
+
+### Testing The App Locally
+
+Once you've built the app, you may test it locally by running `npm run preview` command.
+
+```bash
+$ npm run build
+$ npm run preview
+```
+
+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.
+
+You may configure the port of the server py passing `--port` flag as an argument.
+
+```json
+{
+  "scripts": {
+    "preview": "vite preview --port 8080"
+  }
+}
+```
+
+Now the `preview` method will launch the server at http://localhost:8080.
+
+## GitHub Pages
+
+1. Set the correct `base` in `vite.config.js`.
+
+   If you are deploying to `https://<USERNAME>.github.io/`, you can omit `base` as it defaults to `'/'`.
+
+   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>/'`.
+
+2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately), and run it to deploy:
+
+```bash{13,20,23}
+#!/usr/bin/env sh
+
+# abort on errors
+set -e
+
+# build
+npm run build
+
+# navigate into the build output directory
+cd dist
+
+# if you are deploying to a custom domain
+# echo 'www.example.com' > CNAME
+
+git init
+git add -A
+git commit -m 'deploy'
+
+# if you are deploying to https://<USERNAME>.github.io
+# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master
+
+# if you are deploying to https://<USERNAME>.github.io/<REPO>
+# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
+
+cd -
+```
+
+::: tip
+You can also run the above script in your CI setup to enable automatic deployment on each push.
+:::
+
+### GitHub Pages and Travis CI
+
+1. Set the correct `base` in `vite.config.js`.
+
+   If you are deploying to `https://<USERNAME or GROUP>.github.io/`, you can omit `base` as it defaults to `'/'`.
+
+   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>/'`.
+
+2. Create a file named `.travis.yml` in the root of your project.
+
+3. Run `npm install` locally and commit the generated lockfile (`package-lock.json`).
+
+4. Use the GitHub Pages deploy provider template, and follow the [Travis CI documentation](https://docs.travis-ci.com/user/deployment/pages/).
+
+```yaml
+language: node_js
+node_js:
+  - lts/*
+install:
+  - npm ci
+script:
+  - npm run build
+deploy:
+  provider: pages
+  skip_cleanup: true
+  local_dir: dist
+  # A token generated on GitHub allowing Travis to push code on you repository.
+  # Set in the Travis settings page of your repository, as a secure variable.
+  github_token: $GITHUB_TOKEN
+  keep_history: true
+  on:
+    branch: master
+```
+
+## GitLab Pages and GitLab CI
+
+1. Set the correct `base` in `vite.config.js`.
+
+    If you are deploying to `https://<USERNAME or GROUP>.gitlab.io/`, you can omit `base` as it defaults to `'/'`.
+
+    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>/'`.
+
+2. Set `build.outDir` in `vite.config.js` to `public`.
+
+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:
+
+```yaml
+image: node:10.22.0
+pages:
+  cache:
+    paths:
+      - node_modules/
+  script:
+    - npm install
+    - npm run build
+  artifacts:
+    paths:
+      - public
+  only:
+    - master
+```
+
+## Netlify
+
+1. On [Netlify](https://netlify.com), setup up a new project from GitHub with the following settings:
+
+- **Build Command:** `vite build` or `npm run build`
+- **Publish directory:** `dist`
+
+2. Hit the deploy button.
+
+## Google Firebase
+
+1. Make sure you have [firebase-tools](https://www.npmjs.com/package/firebase-tools) installed.
+
+2. Create `firebase.json` and `.firebaserc` at the root of your project with the following content:
+
+ `firebase.json`:
+
+  ```json
+  {
+    "hosting": {
+      "public": "dist",
+      "ignore": []
+    }
+  }
+  ```
+
+  `.firebaserc`:
+
+  ```js
+  {
+   "projects": {
+     "default": "<YOUR_FIREBASE_ID>"
+   }
+  }
+  ```
+
+3. After running `npm run build`, deploy using the command `firebase deploy`.
+
+## Surge
+
+1. First install [surge](https://www.npmjs.com/package/surge), if you haven’t already.
+
+2. Run `npm run build`.
+
+3. Deploy to surge by typing `surge dist`.
+
+You can also deploy to a [custom domain](http://surge.sh/help/adding-a-custom-domain) by adding `surge dist yourdomain.com`.
+
+## Heroku
+
+1. Install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).
+
+2. Create a Heroku account by [signing up](https://signup.heroku.com).
+
+3. Run `heroku login` and fill in your Heroku credentials:
+
+```bash
+$ heroku login
+```
+
+4. Create a file called `static.json` in the root of your project with the below content:
+
+`static.json`:
+
+```json
+{
+  "root": "./dist"
+}
+```
+
+This is the configuration of your site; read more at [heroku-buildpack-static](/~https://github.com/heroku/heroku-buildpack-static).
+
+5. Set up your Heroku git remote:
+
+```bash
+# version change
+$ git init
+$ git add .
+$ git commit -m "My site ready for deployment."
+
+# creates a new app with a specified name
+$ heroku apps:create example
+
+# set buildpack for static sites
+$ heroku buildpacks:set /~https://github.com/heroku/heroku-buildpack-static.git
+```
+
+6. Deploy your site:
+
+```bash
+# publish site
+$ git push heroku master
+
+# opens a browser to view the Dashboard version of Heroku CI
+$ heroku open
+```
+
+## Vercel
+
+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.
+
+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`
+
+![Override Vercel Configuration](../images/vercel-configuration.png)
+
+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.
+
+Once deployed, you will get a URL to see your app live, such as the following: https://vite.vercel.app