You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: guides/release/addons-and-dependencies/index.md
+7-148Lines changed: 7 additions & 148 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,171 +2,30 @@ As you're developing your Ember app, you are likely to run into common scenarios
2
2
Perhaps you want to use a CSS preprocessor to write your stylesheets, or you want to use a popular JS library, or maybe
3
3
you want to import components written by a different department within your organization.
4
4
5
-
Ember CLI provides a common format called [Ember Addons](#toc_addons) for distributing reusable libraries to solve some
5
+
Ember provides a common format called [Ember Addons](#toc_addons) for distributing reusable libraries to solve some
6
6
of these problems. Additionally, you may want to make use of front-end dependencies like a CSS framework or a JavaScript
7
7
datepicker that aren't specific to Ember apps.
8
8
9
9
## Addons
10
10
11
-
Addons are JavaScript packages that integrate with Ember. For example, [`ember-cli-sass`](https://github.com/adopted-ember-addons/ember-cli-sass)
12
-
is an addon that allows you to use SASS/SCSS in your applications. You can install it using the Ember CLI with the following command:
11
+
Addons are JavaScript packages that integrate with Ember. For example, [`ember-concurrency`](https://github.com/machty/ember-concurrency) provides a concurrency primitive that you can use in your Ember app as well as a [Babel](https://babeljs.io/) plugin that makes it easier to use in an Ember application. You can install it just like any other npm package:
13
12
14
13
```bash
15
-
ember install ember-cli-sass
14
+
npm install --save-dev ember-cli-sass
16
15
```
17
16
18
-
This will modify your `package.json` (and `package-lock.json` or `yarn.lock` or `pnpm-lock.yaml`), typically bringing in other dependencies. Some addons will also add
19
-
additional files to your projects when relevant.
20
-
21
-
There are many addons that cover all kinds of use cases. For more detail, as well as examples of what addons can do,
22
-
we invite you to have a look at the [Ember CLI documentation](https://cli.emberjs.com/release/basic-use/using-addons/).
17
+
And then follow any additional instructions in the README of the addon. Some addons (like `ember-concurrency`) will give instructions for extra steps that you might need like installing a Babel plugin so it's always worthwhile reading the installation documentation.
23
18
24
19
The Ember community publishes and maintains many addons, and it can be difficult to know if one (or many!) exists that covers
25
20
your needs. The website [Ember Observer](https://www.emberobserver.com/) keeps an up-to-date index of Ember Addons, sorted by
26
21
categories, and rated according to objective metrics. If you are looking for an addon, we recommend that you start there!
27
22
28
23
## Regular npm packages
29
24
30
-
While dependencies can be managed in several ways,
31
-
it's worth noting that the process can be greatly simplified for new developers by using ember-auto-import,
32
-
which offers zero config imports from npm packages.
33
-
It's built into new Ember apps by default and can be installed in older apps by using `ember install ember-auto-import`.
34
-
For further usage instructions, please follow the [project README](https://github.com/ef4/ember-auto-import).
35
-
36
-
## Other assets
37
-
38
-
Third-party JavaScript not available as an addon or npm package should be placed in the `vendor/` folder in your project.
39
-
40
-
Your own assets (such as `robots.txt`, `favicon`, custom fonts, etc) should be placed in the `public/` folder in your project.
41
-
42
-
## Compiling Assets
43
-
44
-
When you're using dependencies that are not included in an addon,
45
-
you will have to instruct Ember CLI to include your assets in the build.
46
-
This is done using the asset manifest file `ember-cli-build.js`.
47
-
You should only try to import assets located in the `node_modules` and `vendor` folders.
48
-
49
-
### Globals provided by JavaScript assets
50
-
51
-
The globals provided by some assets (like `moment` in the below example) can be used in your application
52
-
without the need to `import` them.
53
-
Provide the asset path as the first and only argument.
54
-
55
-
```javascript {data-filename=ember-cli-build.js}
56
-
app.import('node_modules/moment/moment.js');
57
-
```
58
-
59
-
You will need to add `"moment"` to the `globals` section in `.eslintrc.js` to prevent ESLint errors
60
-
about using an undefined variable.
61
-
62
-
### Anonymous AMD JavaScript modules
63
-
64
-
You can transform an anonymous AMD module to a named one by using the `amd` transformation.
65
-
66
-
```javascript {data-filename=ember-cli-build.js}
67
-
app.import('node_modules/moment/moment.js', {
68
-
using: [
69
-
{ transformation:'amd', as:'moment' }
70
-
]
71
-
});
72
-
```
73
-
74
-
This transformation allows you to `import` moment in your app. (e.g. `import moment from 'moment';`)
75
-
76
-
### CommonJS JavaScript modules
77
-
78
-
[ember-cli-cjs-transform](https://github.com/rwjblue/ember-cli-cjs-transform) allows us to import CommonJS modules into
79
-
our Ember app. It also does auto-rollup and some nice caching, so it should pull in all the deps that are pulled in
80
-
with `require` for you automatically. It is not yet included with Ember CLI by default, so you will need to install it.
You can now `import` them in your app. (e.g. `import showdown from 'showdown';`)
95
-
96
-
### Environment-Specific Assets
25
+
For newly generated Ember apps, the majority of the build is managed by [Vite](https://vite.dev/) which means that any npm packages or other assets can just be imported as you might expect in a modern build system or bundler.
97
26
98
-
If you need to use different assets in different environments, specify an object as the first parameter.
99
-
That object's key should be the environment name, and the value should be the asset to use in that environment.
27
+
In previous versions of Ember (before we moved to using Vite) there were other concepts that you would need to know to include 3rd party packages or assets in your app. If you are working on an Ember app that hasn't yet been upgraded to Vite you should look at [previous versions of this guide](/v6.7.0/addons-and-dependencies/) to get more information about the legacy build system.
If you need to load certain dependencies before others,
162
-
you can set the `prepend` property equal to `true` on the second argument of `import()`.
163
-
This will prepend the dependency to the vendor file instead of appending it, which is the default behavior.
164
-
165
-
```javascript {data-filename=ember-cli-build.js}
166
-
app.import('node_modules/es5-shim/es5-shim.js', {
167
-
type:'vendor',
168
-
prepend:true
169
-
});
170
-
```
29
+
To know more about how Vite can be configured, e.g. how it [handles static assets](https://vite.dev/guide/assets), you can consult their guides: [https://vite.dev/guide/](https://vite.dev/guide/)
171
30
172
31
<!-- eof - needed for pages that end in a code block -->
- 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.
4
+
- The legacy [ember-cli based build](https://cli.emberjs.com/release/) is also still supported on all Ember versions.
5
+
6
+
You can tell which one you're using based on the presence of `@embroider/vite` in your `package.json` file.
7
+
8
+
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.
9
+
10
+
On Ember versions after 6.8, you can optionally choose to generate a new app using the older build environment via:
11
+
12
+
```sh
13
+
npx ember-cli@ new my-app-name -b @ember-tooling/classic-build-app-blueprint
When you generate a new Ember app your default build system will be using Vite.
2
+
3
+
> Vite is a blazing fast frontend build tool powering the next generation of web applications.
4
+
5
+
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.
6
+
7
+
## Basic Usage
8
+
9
+
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.
10
+
11
+
You can see more docs on these commands in the Vite documentation
12
+
13
+
### Sensible defaults
14
+
15
+
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/
16
+
17
+
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.
18
+
19
+
20
+
### Integrating 3rd party plugins
21
+
22
+
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.
23
+
24
+
## Advanced Usage
25
+
26
+
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.
27
+
28
+
### Running Tests Against Production Code
29
+
30
+
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.
31
+
32
+
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.
Ember application builds are created by the Ember CLI build pipeline. Just as with your application code,
2
-
Ember CLI ships with a sensible set of defaults to compile and bundle the assets that can be deployed
3
-
to production. Under the hood, this is accomplished using a series of Broccoli plugins, each of which
4
-
can be configured in the `ember-cli-build.js` file at the root of your project.
5
-
6
-
Ember CLI uses [Babel.js](https://babeljs.io/) for the compile step in this process. If you've used Babel
7
-
before, you know that it comes with a large set of options, including the ability to configure
8
-
"targets"; i.e. the environments in which your application is expected to run.
9
-
For example, if your application is embedded in an [Electron app](https://www.electronjs.org),
10
-
you might only care about compiling for the latest Chromium build. Or if your app targets Enterprise
11
-
users, you may need to compile your JavaScript to older syntax that runs in IE11.
12
-
13
-
For any of these cases, you can configure `ember build` to do The Right Thing. You can read more about
14
-
this in [the Ember CLI Guides](https://cli.emberjs.com/release/advanced-use/build-targets/)!
1
+
By default, Ember apps are built with Vite. The toolchain uses Babel, esbuild, and Rollup so you can write current-generation JavaScript and TypeScript while still allowing your application to work with older browsers.
2
+
3
+
Rather than always compiling everything down to legacy syntax, Ember determines what—if anything—needs to be transformed based on the browsers you target. With today’s defaults aimed at evergreen browsers, many features (ES modules, classes, arrow functions, async/await, etc.) ship largely as-is.
4
+
5
+
Why does this matter? Over-transpiling to very old JavaScript increases bundle size, slows parsing, and in some cases can slow down the execution of your JavaScript code. As the Web platform has advanced and percentage of users on legacy browsers have decreased, Ember’s default targets avoid unnecessary transforms to keep apps smaller and faster.
6
+
7
+
If you need to update the defaults for any reason (i.e. need to target a very legacy browser), you can set the targets for your app and the compiler applies only the minimal transforms and polyfills required for those browsers.
8
+
9
+
If you open `config/targets.js`, you will find the following code:
10
+
11
+
```javascript {data-filename=config/targets.js}
12
+
"use strict";
13
+
14
+
constbrowsers= [
15
+
"last 1 Chrome versions",
16
+
"last 1 Firefox versions",
17
+
"last 1 Safari versions",
18
+
];
19
+
20
+
module.exports= {
21
+
browsers,
22
+
};
23
+
```
24
+
25
+
If you inspect your compiled code after running a build with `npm run build`, you'll see that many modern features (like arrow functions and async/await) preserved when your targets support them.
26
+
27
+
This feature is backed by [Browserslist](https://github.com/ai/browserslist) and [Can I Use](https://caniuse.com/).
28
+
These websites track usage stats of browsers, so you can use complex queries based on the user base of every browser.
29
+
30
+
If you want to target all browsers with more than a 4% market share in Canada,
31
+
you'd have the following options:
32
+
33
+
```javascript {data-filename=config/targets.js}
34
+
module.exports= {
35
+
browsers: ["> 4% in CA"],
36
+
};
37
+
```
38
+
39
+
It is very important that you properly configure the targets of your app so you get the smallest and fastest code possible.
0 commit comments