diff --git a/guides/code-editors/index.md b/guides/code-editors/index.md index 33f8ac56a..d2a038baf 100644 --- a/guides/code-editors/index.md +++ b/guides/code-editors/index.md @@ -7,12 +7,13 @@ many of which are created and maintained by the developer community: Visual Studio Code is a code editor optimized for building and debugging modern web applications. Visual Studio Code is one of the most popular text editors among Ember developers. -### Syntax Highlighting +### Extension Pack + +Install the extension pack to get everything you need to work on Ember.js projects. -Only one of these is needed. +[Ember.js Extension Pack](https://marketplace.visualstudio.com/items?itemName=EmberTooling.emberjs) - It will install the following addons -[VSCode Glimmer](https://marketplace.visualstudio.com/items?itemName=chiragpat.vscode-glimmer) - -Provides embedded template highlighting support. +### Syntax Highlighting [Glimmer Templates Syntax](https://marketplace.visualstudio.com/items?itemName=lifeart.vscode-glimmer-syntax) - Syntax formatting for glimmer templates. @@ -22,10 +23,9 @@ Syntax formatting for glimmer templates. [Stable Ember Language Server](https://marketplace.visualstudio.com/items?itemName=lifeart.vscode-ember-unstable) - Stable Ember Language Server is a stable, full-featured language server. Its name comes from its history as a fork of Ember Language Server and the efforts to keep up with changes in Ember. -### Snippets / Workflow +### Workflow -[Ember JS (ES6) and Handlebars code snippets](https://marketplace.visualstudio.com/items?itemName=phanitejakomaravolu.EmberES6Snippets) - -Enables Ember.js and Handlebars snippets to let you to type less and code more. +[ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Integrates ESLint into VS Code. [EditorConfig for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) - Attempts to override user/workspace settings with settings found in `.editorconfig` files. @@ -35,9 +35,21 @@ and maintain consistent coding styles between different editors and IDEs. [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Prettier is an opinionated code formatting tool. It enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary. Prettier supports Handlebars, Ember and Glimmer out of the box. -### Glimmer templates +### Typed Glimmer Templates + +
+
+
+
Zoey says...
+
+ This is not installed as part of the extension pack but should be considered for Ember projects built with TypeScript. Learn more about Glint here. +
+
+ +
+
-[Glint](https://marketplace.visualstudio.com/items?itemName=typed-ember.glint-vscode) is a set of tools to aid in developing code that uses the Glimmer VM for rendering, such as Ember.js v3.24+ and GlimmerX projects. +[Glint](https://marketplace.visualstudio.com/items?itemName=typed-ember.glint-vscode) is a set of tools to aid in developing code that uses the Glimmer VM for rendering, such as Ember.js v3.24+ and GlimmerX projects. ## Vim and Neovim @@ -63,10 +75,10 @@ or [vim-ember-hbs](https://github.com/joukevandermaas/vim-ember-hbs) - Add Ember template syntax highlighting and indentation to Vim. To get embedded highlighting will involve these additional plugins: + - [vim-javascript](https://github.com/pangloss/vim-javascript) - [vim-js-pretty-template](https://github.com/Quramy/vim-js-pretty-template) - ### Language Server Only one of these solutions should be used at a time. @@ -78,21 +90,18 @@ Example mason+LSP config [can be found here](https://github.com/NullVoxPopuli/do or [Conquer for Completion (COC) for Neovim](https://github.com/neoclide/coc.nvim) - -An Intellisense engine which takes control over all linting, hinting, and language-server integration. +An IntelliSense engine which takes control over all linting, hinting, and language-server integration. With the ember plugin [coc-ember](https://github.com/NullVoxPopuli/coc-ember) - Ember.js language server extension including useful configuration instructions. ### Snippets / Workflow - [ember.vim](https://github.com/dsawardekar/ember.vim) - Shortcuts to navigate related files with Ember.js projects. - [Ember Tools](https://github.com/AndrewRadev/ember_tools.vim) - Various tools for working with Ember.js projects. - ## Atom Atom is hackable text editor for the 21st Century. diff --git a/guides/components/template-lifecycle-dom-and-modifiers.md b/guides/components/template-lifecycle-dom-and-modifiers.md index b8fb711cf..13fa0e8c5 100644 --- a/guides/components/template-lifecycle-dom-and-modifiers.md +++ b/guides/components/template-lifecycle-dom-and-modifiers.md @@ -293,10 +293,17 @@ The modifier that we're going to build will allow us to say: Pretty nice, right? -To accomplish that, we'll create a modifier in `app/modifiers/autofocus.js`. First, install [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) and then generate an `autofocus` modifier for your app: +New Ember apps ship with a dependency on +[ember-modifier](https://github.com/ember-modifier/ember-modifier), which +provides a friendly API for writing your own element modifiers. This library is +in turn based on a low level API named _modifier managers_. Managers are a +framework-development level feature, and not something most developers need to +interact with. You'll see in the following examples that the modifier API is +imported from the `ember-modifier` package. + +First generate the `autofocus` modifier for your application: ```bash -ember install ember-modifier ember generate modifier autofocus ``` @@ -308,9 +315,10 @@ import { modifier } from "ember-modifier"; export default modifier(element => element.focus()); ``` -And that's it! +And that's it! Now we can use our custom `{{autofocus}}` modifier throughout our application. -Now we can use our custom `{{autofocus}}` modifier throughout our application. +Read more about the `ember-modifier` APIs at [ember-modifiers: +Usage](https://github.com/ember-modifier/ember-modifier#usage). ## Communicating Between Elements in a Component @@ -390,7 +398,6 @@ export default class AudioPlayerComponent extends Component { That's it for the component: we're translating the user's interactions into _state_. Now we need to build a modifier to translate the state into the appropriate DOM method calls! ```bash -ember install ember-modifier ember generate modifier play-when ``` @@ -448,12 +455,11 @@ document.addEventListener("click", event => { The most important difference between this example and the cases we've seen so far is that we need to remove the `click` event handler from the document when this element is destroyed. -To accomplish this, we can use [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) to create a `on-click-outside` modifier that sets up the event listener after the element is first inserted and removes the event listener when the element is removed. +To accomplish this, we can use [`ember-modifier`](https://github.com/ember-modifier/ember-modifier) (which is already installed in newly generated Ember apps) to create a `on-click-outside` modifier that sets up the event listener after the element is first inserted and removes the event listener when the element is removed. -Run the following commands to install the addon and generate a new modifier: +Generate the new modifier: ```bash -ember install ember-modifier ember generate modifier on-click-outside ``` diff --git a/guides/testing/index.md b/guides/testing/index.md index af9460b05..46eb499a6 100644 --- a/guides/testing/index.md +++ b/guides/testing/index.md @@ -34,7 +34,7 @@ ember t -s When you are working on a single component or page, you will want only a small subset of tests to run after every file change. To specify which tests to run, you can add `--module` or `--filter` option to your command. -The `--module` option allows you to select a **module**—a group of tests that you specified in `module()` in QUnit, or `describe()` in Mocha. +The `--module` option allows you to select a **module**—a group of tests that you specified in `module()` in QUnit. ```bash # Button component example @@ -44,7 +44,7 @@ ember test --server --module="Integration | Component | simple-button" ember t -s -m="Unit | Service | location" ``` -The `--filter` option is more versatile. You can provide a phrase to match against the modules and test descriptions. A test description is what appears in `test()` in QUnit, or `it()` in Mocha. +The `--filter` option is more versatile. You can provide a phrase to match against the modules and test descriptions. A test description is what appears in `test()` in QUnit. ```bash # Button component example @@ -57,7 +57,7 @@ ember t -s -f="Dashboard" ember t -s -f="Integration" ``` -In QUnit, you can exclude tests by adding an exclamation point to the beginning of the filter, e.g. `ember test --filter="!Acceptance"`. In Mocha, `ember test --filter="Acceptance" --invert`. +In QUnit, you can exclude tests by adding an exclamation point to the beginning of the filter, e.g. `ember test --filter="!Acceptance"`. To learn more about options for testing, you can visit [Ember CLI Documentation](https://ember-cli.com/testing) or type `ember help test` in the command line. diff --git a/guides/testing/testing-tools.md b/guides/testing/testing-tools.md index 222e82d45..71e50bfa3 100644 --- a/guides/testing/testing-tools.md +++ b/guides/testing/testing-tools.md @@ -164,6 +164,6 @@ While we don't recommend this practice in general, you might also use Percy in l ## Summary -Ember provides easy paths to integrate QUnit and Mocha, also it supports a variety of addons and debugging tools to improve your developer experience in testing. +Ember provides easy paths to integrate QUnit and it also supports a variety of addons and debugging tools to improve your developer experience in testing. In the next section, we will study 3 types of tests that Ember supports—unit, rendering, and application tests. We will look at each type and when you might use one over another. diff --git a/guides/typescript/additional-resources/faq.md b/guides/typescript/additional-resources/faq.md new file mode 100644 index 000000000..561555734 --- /dev/null +++ b/guides/typescript/additional-resources/faq.md @@ -0,0 +1,89 @@ +## What about missing types? + +### Gradually typing your app + +See ["Gradual Typing Hacks"][gradual-typing-hacks] for strategies for incrementally adding types to your app. + +### Install types for libraries + +You'll want to use library type definitions as much as possible. Many packages ship their own type definitions, and many others have community-maintained definitions from [DefinitelyTyped][], available in the `@types` name space. The first thing you should do is to look for types from other libraries: it will mean using fewer ["Gradual Typing Hacks"][gradual-typing-hacks] and getting a lot more help both from your editor and from the compiler. + +### The `types` directory + +During installation, we create a `types` directory in the root of your application and add a [`"paths"`][tsconfig-paths] mapping to your `tsconfig.json` that includes that directory in any type lookups TypeScript tries to do. This is convenient for a few things: + +- global types for your project (see the next section) +- writing types for libraries that do not have any types + +These are all fallbacks, of course, you should use the types supplied directly with a package when possible. + +#### Global types for your project + +At the root of your application or addon, we include a `types/` directory with an `index.d.ts` file in it. Anything which is part of your project but which must be declared globally can go in this file. For example, if you have data attached to the `Window` object when the page is loaded (for bootstrapping or whatever other reason), this is a good place to declare it. + +We automatically configure `index.d.ts` to be ready for [Glint][], which will make type checking work with Ember's templates. The default configuration only supports Ember's classic pairing of separate `.ts` and `.hbs` files, but Glint also supports the `