From 17c63feab47d37a42220505762c7ca0ad8150482 Mon Sep 17 00:00:00 2001 From: patak Date: Thu, 22 Jun 2023 11:00:40 +0200 Subject: [PATCH] docs: project philosophy (#12897) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Arnaud Barré Co-authored-by: Jeff Yang Co-authored-by: bluwy --- CONTRIBUTING.md | 2 +- docs/.vitepress/config.ts | 4 ++++ docs/guide/philosophy.md | 27 +++++++++++++++++++++++++++ 3 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 docs/guide/philosophy.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c8e2efaf021e2..5933404093e3e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Vite Contributing Guide -Hi! We're really excited that you're interested in contributing to Vite! Before submitting your contribution, please read through the following guide. +Hi! We're really excited that you're interested in contributing to Vite! Before submitting your contribution, please read through the following guide. We also suggest you read the [Project Philosophy](https://vitejs.dev/guide/philosophy) in our documentation. You can use [StackBlitz Codeflow](https://stackblitz.com/codeflow) to fix bugs or implement features. You'll see a Codeflow button on issues to start a PR to fix them. A button will also appear on PRs to review them without needing to check out the branch locally. When using Codeflow, the Vite repository will be cloned for you in an online editor, with the Vite package built in watch mode ready to test your changes. If you'd like to learn more, check out the [Codeflow docs](https://developer.stackblitz.com/codeflow/what-is-codeflow). diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 22ebb5f233fef1..26db9f54bd3194 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -235,6 +235,10 @@ export default defineConfig({ text: 'Troubleshooting', link: '/guide/troubleshooting', }, + { + text: 'Philoshophy', + link: '/guide/philosophy', + }, { text: 'Migration from v3', link: '/guide/migration', diff --git a/docs/guide/philosophy.md b/docs/guide/philosophy.md new file mode 100644 index 00000000000000..b4a74ba7306a5f --- /dev/null +++ b/docs/guide/philosophy.md @@ -0,0 +1,27 @@ +# Project Philosophy + +## Lean Extendable Core + +Vite doesn't intend to cover every use case for every user. Vite aims to support the most common patterns to build Web apps out-of-the-box, but [Vite core](https://github.com/vitejs/vite) must remain lean with a small API surface to keep the project maintainable long-term. This goal is possible thanks to [Vite's rollup-based plugin system](./api-plugin.md). Features that can be implemented as external plugins will generally not be added to Vite core. [vite-plugin-pwa](https://vite-pwa-org.netlify.app/) is a great example of what can be achieved out of Vite core, and there are a lot of [well maintained plugins](https://github.com/vitejs/awesome-vite#plugins) to cover your needs. Vite works closely with the Rollup project to ensure that plugins can be used in both plain-rollup and Vite projects as much as possible, trying to push needed extensions to the Plugin API upstream when possible. + +## Pushing the Modern Web + +Vite provides opinionated features that pushes writing modern code. For example: + +- The source code can only be written in ESM, where non-ESM dependencies needs to be [pre-bundled as ESM](./dep-pre-bundling) in order to work. +- Web workers are encouraged to be written with the [`new Worker` syntax](./features#web-workers) to follow modern standards. +- Node.js modules cannot be used in the browser. + +When adding new features, these patterns are followed to create a future-proof API, which may not always be compatible with other build tools. + +## A Pragmatic Approach to Performance + +Vite has been focused on performance since its [origins](./why.md). Its dev server architecture allows HMR that stays fast as projects scale. Vite uses native tools like [esbuild](https://esbuild.github.io/) and [SWC](https://github.com/vitejs/vite-plugin-react-swc) to implement intensive tasks but keeps the rest of the code in JS to balance speed with flexibility. When needed, framework plugins will tap into [Babel](https://babeljs.io/) to compile user code. And during build time Vite currently uses [Rollup](https://rollupjs.org/) where bundling size and having access to a wide ecosystem of plugins are more important than raw speed. Vite will continue to evolve internally, using new libraries as they appear to improve DX while keeping its API stable. + +## Building Frameworks on top of Vite + +Although Vite can be used by users directly, it shines as a tool to create frameworks. Vite core is framework agnostic, but there are polished plugins for each UI frameworks. Its [JS API](./api-javascript.md) allows App Framework authors to use Vite features to create tailored experiences for their users. Vite includes support for [SSR primitives](./ssr.md), usually present in higher-level tools but fundamental to building modern web frameworks. And Vite plugins complete the picture by offering a way to share between frameworks. Vite is also a great fit when paired with [Backend frameworks](./backend-integration.md) like [Ruby](https://vite-ruby.netlify.app/) and [Laravel](https://laravel.com/docs/10.x/vite). + +## An Active Ecosystem + +Vite evolution is a cooperation between framework and plugin maintainers, users, and the Vite team. We encourage active participation in Vite's Core development once a project adopts Vite. We work closely with the main projects in the ecosystem to minimize regressions on each release, aided by tools like [vite-ecosystem-ci](https://github.com/vitejs/vite-ecosystem-ci). It allows us to run the CI of major projects using Vite on selected PRs and gives us a clear status of how the Ecosystem would react to a release. We strive to fix regressions before they hit users and allow projects to update to the next versions as soon as they are released. If you are working with Vite, we invite you to join [Vite's Discord](https://chat.vitejs.dev) and get involved in the project too.