Merge pull request #2168 from ember-learn/build-tools

add basic landing pages for Vite build systems

Author: mansona

.local.dic

@@ -52,6 +52,7 @@ debounce
 declaratively
 DefinitelyTyped
 deps
+dev
 draggable
 dropdown
 durations
@@ -180,6 +181,7 @@ rerender
 rerendering
 rerenders
 RequestManager
+rollup
 Rollup
 routable
 RunDOC
@@ -257,5 +259,6 @@ working-with-html-css-and-javascript
 yay
 ZEIT
 userQuestion
+vite
 Vite
 bundler

guides/release/build-tools/index.md

@@ -0,0 +1,17 @@
+Ember supports two different build environments:
+
+ - Our [Vite integration](./vite) works on all Ember versions back to 3.28. It became the default for newly-generated apps at Ember 6.8.
+ - The legacy [ember-cli based build](https://cli.emberjs.com/release/) is also still supported on all Ember versions.
+
+You can tell which one you're using based on the presence of `@embroider/vite` in your `package.json` file.
+
+Existing apps can use [Ember Vite Codemod](https://github.com/mainmatter/ember-vite-codemod) to switch from the ember-cli based build to the Vite based build.
+
+On Ember versions after 6.8, you can optionally choose to generate a new app using the older build environment via:
+
+```sh
+npx ember-cli@ new my-app-name -b @ember-tooling/classic-build-app-blueprint
+```
+
+
+

guides/release/build-tools/vite.md

@@ -0,0 +1,32 @@
+When you generate a new Ember app your default build system will be using Vite.
+
+> Vite is a blazing fast frontend build tool powering the next generation of web applications.
+
+You can read more about [Vite on their documentation](https://vite.dev/guide/) site. Ember's Vite implementation is [powered by Embroider](https://github.com/embroider-build/embroider), which acts as a Vite plugin that allows Vite to effectively build an Ember app.
+
+## Basic Usage
+
+For most developers the only interaction that they will have with the build system is running the `npm start`, or `npm run build` scripts defined in their `package.json`. If you have a look at your `package.json` scripts you will see that they are just deferring to `vite` (which by default runs `vite dev` and starts the Vite dev server) and `vite build` respectively.
+
+You can see more docs on these commands in the Vite documentation
+
+### Sensible defaults
+
+As Ember developers we expect reasonable defaults, because of that we have provided a default vite config for you that takes care of most of the Vite configuration you need as an Ember developer. For example, we automatically include your `tests/index.html` in the `build.rollupOptions.input` when you are building in `develoment` mode so that you can navigate to http://localhost:4200/tests/ 
+
+For most applications you will not need to override the config that we provide by default, instead you can just add to the config as you need. If you do need to change the defaults that we provide, you can just define the new configuration in your `vite.config.js` because anything you define there will take precedence over anything we provide.
+
+
+### Integrating 3rd party plugins
+
+Now that Ember uses Vite for its build system, you no longer need an Ember-specific plugin to augment your build. If you find a Vite or rollup plugin that you would like to use you can follow the installation instructions to add that to your `vite.config.js` without any Ember-specific instructions necessary.
+
+## Advanced Usage
+
+Most developers will not need to change the defaults that we provide, but in some rare cases it can be useful to know how to change the defaults.
+
+### Running Tests Against Production Code
+
+By default, we don't build your tests when you build for production. This is because, in most cases, people don't want their tests included in the bundle they ship to end-users. This means if you run `npm run build` in your app it will default to `--mode production` (because this is [the default for `vite build`](https://vite.dev/config/shared-options.html#mode)) and it will not include your tests in your build output.
+
+If you needed to run your tests against your production environment for any reason (maybe you have a vite/rollup plugin that you only run during your production build) then you can use the `FORCE_BUILD_TESTS=true` environment variable. This is just a convenience in the code that the default `ember()` plugin provides, you can always define your inputs in the `vite.config.js` which will take precedent over anything we're doing automatically for you in the `ember()` plugin.

guides/release/pages.yml

@@ -298,6 +298,13 @@
 - title: "Developer Tools"
   url: "toc-heading_developer-tools"
   is_heading: true
+- title: "Build Tooling"
+  url: "build-tools"
+  pages:
+    - title: "Introduction"
+      url: "index"
+    - title: "Vite"
+      url: "vite"
 - title: "Ember Inspector"
   url: "ember-inspector"
   pages:

tests/acceptance/side-bar-links-test.js

@@ -27,7 +27,7 @@ module('Acceptance | side bar links', function (hooks) {
 
   test('release links go to correct page', async function (assert) {
     // Manually update this number when new pages are added or removed
-    assert.expect(125);
+    assert.expect(127);
     await visit('/release');
 
     let store = this.owner.lookup('service:store');