diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index dbedcdb2549900..987577ee99a226 100644 --- a/docs/.vitepress/config.js +++ b/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' diff --git a/docs/guide/build.md b/docs/guide/build.md index 6e3c49252607e0..0f8ea3f681f25e 100644 --- a/docs/guide/build.md +++ b/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 `/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 `/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 diff --git a/docs/guide/static-deploy.md b/docs/guide/static-deploy.md new file mode 100644 index 00000000000000..48dc91fe1a8b53 --- /dev/null +++ b/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://.github.io/`, you can omit `base` as it defaults to `'/'`. + + If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `'//'`. + +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://.github.io +# git push -f git@github.com:/.github.io.git master + +# if you are deploying to https://.github.io/ +# git push -f git@github.com:/.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://.github.io/`, you can omit `base` as it defaults to `'/'`. + + If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `'//'`. + +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://.gitlab.io/`, you can omit `base` as it defaults to `'/'`. + + If you are deploying to `https://.gitlab.io//`, for example your repository is at `https://gitlab.com//`, then set `base` to `'//'`. + +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": "" + } + } + ``` + +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 diff --git a/docs/images/vercel-configuration.png b/docs/images/vercel-configuration.png new file mode 100644 index 00000000000000..def83c8be806d3 Binary files /dev/null and b/docs/images/vercel-configuration.png differ