├── .alexrc ├── .editorconfig ├── .ember-cli ├── .eslintignore ├── .eslintrc.js ├── .github └── workflows │ └── ci.yml ├── .gitignore ├── .local.dic ├── .netlifyheaders ├── .netlifyredirects ├── .node-version ├── .prettierignore ├── .prettierrc.js ├── .remarkignore ├── .remarkrc.js ├── .template-lintrc.js ├── .watchmanconfig ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── app ├── app.js ├── index.html ├── router.js └── styles │ └── app.css ├── config ├── ember-cli-update.json ├── environment.js ├── fastboot.js ├── optional-features.json └── targets.js ├── ember-cli-build.js ├── guides ├── advanced-use │ ├── asset-compilation.md │ ├── blueprints.md │ ├── build-targets.md │ ├── cli-commands-reference.md │ ├── debugging.md │ ├── file-layout.md │ ├── index.md │ ├── project-layouts.md │ └── stylesheets.md ├── api-documentation │ └── index.md ├── appendix │ ├── common-issues.md │ ├── configuration.md │ ├── dev-tools.md │ ├── faq.md │ ├── index.md │ ├── live-reload.md │ └── windows.md ├── basic-use │ ├── assets-and-dependencies.md │ ├── cli-commands.md │ ├── configurations.md │ ├── deploying.md │ ├── folder-layout.md │ ├── index.md │ ├── upgrading.md │ └── using-addons.md ├── index.md ├── pages.yml └── writing-addons │ ├── addon-blueprints.md │ ├── addon-dependencies.md │ ├── custom-commands.md │ ├── deploying.md │ ├── deprecations.md │ ├── documenting.md │ ├── in-repo-addons.md │ ├── index.md │ ├── intro-tutorial.md │ ├── testing.md │ └── wrappers.md ├── node-tests └── link-checker.js ├── package-lock.json ├── package.json ├── public ├── assets │ └── images │ │ ├── enabling-symlinks.png │ │ └── run-as-admin.png └── robots.txt ├── testem.js └── tests ├── index.html └── test-helper.js /.alexrc: -------------------------------------------------------------------------------- 1 | { 2 | "allow": [ 3 | "disabled", 4 | "dummy", 5 | "host-hostess", 6 | "invalid", 7 | "special", 8 | "watchman-watchwoman" 9 | ], 10 | "profanitySureness": 1 11 | } 12 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig helps developers define and maintain consistent 2 | # coding styles between different editors and IDEs 3 | # editorconfig.org 4 | 5 | root = true 6 | 7 | [*] 8 | end_of_line = lf 9 | charset = utf-8 10 | trim_trailing_whitespace = true 11 | insert_final_newline = true 12 | indent_style = space 13 | indent_size = 2 14 | 15 | [*.hbs] 16 | insert_final_newline = false 17 | 18 | [*.{diff,md}] 19 | trim_trailing_whitespace = false 20 | -------------------------------------------------------------------------------- /.ember-cli: -------------------------------------------------------------------------------- 1 | { 2 | /** 3 | Ember CLI sends analytics information by default. The data is completely 4 | anonymous, but there are times when you might want to disable this behavior. 5 | 6 | Setting `disableAnalytics` to true will prevent any data from being sent. 7 | */ 8 | "disableAnalytics": false 9 | } 10 | -------------------------------------------------------------------------------- /.eslintignore: -------------------------------------------------------------------------------- 1 | # unconventional js 2 | /blueprints/*/files/ 3 | /vendor/ 4 | 5 | # compiled output 6 | /dist/ 7 | /tmp/ 8 | 9 | # dependencies 10 | /bower_components/ 11 | /node_modules/ 12 | 13 | # misc 14 | /coverage/ 15 | !.* 16 | .*/ 17 | .eslintcache 18 | 19 | # ember-try 20 | /.node_modules.ember-try/ 21 | /bower.json.ember-try 22 | /package.json.ember-try 23 | /node_modules/ 24 | -------------------------------------------------------------------------------- /.eslintrc.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = { 4 | root: true, 5 | parser: 'babel-eslint', 6 | parserOptions: { 7 | ecmaVersion: 2018, 8 | sourceType: 'module', 9 | ecmaFeatures: { 10 | legacyDecorators: true, 11 | }, 12 | }, 13 | plugins: ['ember'], 14 | extends: [ 15 | 'eslint:recommended', 16 | 'plugin:ember/recommended', 17 | 'plugin:prettier/recommended', 18 | ], 19 | env: { 20 | browser: true, 21 | }, 22 | rules: {}, 23 | overrides: [ 24 | // node files 25 | { 26 | files: [ 27 | './.eslintrc.js', 28 | './.prettierrc.js', 29 | './.template-lintrc.js', 30 | './ember-cli-build.js', 31 | './testem.js', 32 | './blueprints/*/index.js', 33 | './config/**/*.js', 34 | './lib/*/index.js', 35 | './server/**/*.js', 36 | ], 37 | parserOptions: { 38 | sourceType: 'script', 39 | }, 40 | env: { 41 | browser: false, 42 | node: true, 43 | }, 44 | plugins: ['node'], 45 | extends: ['plugin:node/recommended'], 46 | rules: { 47 | // this can be removed once the following is fixed 48 | // https://github.com/mysticatea/eslint-plugin-node/issues/77 49 | 'node/no-unpublished-require': 'off', 50 | }, 51 | }, 52 | { 53 | // Test files: 54 | files: ['tests/**/*-test.{js,ts}'], 55 | extends: ['plugin:qunit/recommended'], 56 | }, 57 | ], 58 | }; 59 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | pull_request: 8 | 9 | env: 10 | NODE_VERSION: 20 11 | 12 | jobs: 13 | lint: 14 | name: Lint files 15 | runs-on: ubuntu-latest 16 | timeout-minutes: 3 17 | steps: 18 | - name: Check out a copy of the repo 19 | uses: actions/checkout@v2 20 | 21 | - name: Use Node.js ${{ env.NODE_VERSION }} 22 | uses: actions/setup-node@v2 23 | with: 24 | node-version: ${{ env.NODE_VERSION }} 25 | 26 | - run: npm install -g npm@7 27 | - run: npm ci 28 | 29 | - name: Lint 30 | run: npm run lint 31 | 32 | 33 | test-app: 34 | name: Test app 35 | runs-on: ubuntu-latest 36 | timeout-minutes: 3 37 | steps: 38 | - name: Check out a copy of the repo 39 | uses: actions/checkout@v2 40 | 41 | - uses: mansona/npm-lockfile-version@v1 42 | 43 | - name: Use Node.js ${{ env.NODE_VERSION }} 44 | uses: actions/setup-node@v2 45 | with: 46 | node-version: ${{ env.NODE_VERSION }} 47 | 48 | - run: npm install -g npm@7 49 | - run: npm ci 50 | 51 | - name: Test 52 | run: npm run test:ember 53 | 54 | 55 | test-node: 56 | name: Test node-tests 57 | runs-on: ubuntu-latest 58 | timeout-minutes: 3 59 | steps: 60 | - name: Check out a copy of the repo 61 | uses: actions/checkout@v2 62 | 63 | - name: Use Node.js ${{ env.NODE_VERSION }} 64 | uses: actions/setup-node@v2 65 | with: 66 | node-version: ${{ env.NODE_VERSION }} 67 | 68 | - run: npm install -g npm@7 69 | - run: npm ci 70 | 71 | - name: Test 72 | run: npm run test:node 73 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # See https://help.github.com/ignore-files/ for more about ignoring files. 2 | 3 | # compiled output 4 | /dist/ 5 | /tmp/ 6 | 7 | # dependencies 8 | /bower_components/ 9 | /node_modules/ 10 | 11 | # misc 12 | /.env* 13 | /.pnp* 14 | /.sass-cache 15 | /.eslintcache 16 | /connect.lock 17 | /coverage/ 18 | /libpeerconnection.log 19 | /npm-debug.log* 20 | /testem.log 21 | /yarn-error.log 22 | 23 | # ember-try 24 | /.node_modules.ember-try/ 25 | /bower.json.ember-try 26 | /package.json.ember-try 27 | -------------------------------------------------------------------------------- /.local.dic: -------------------------------------------------------------------------------- 1 | .scss 2 | .vimrc 3 | *ember 4 | *NPM 5 | *semver 6 | api 7 | Autocomplete 8 | Autoprefixer 9 | autosave 10 | autosaves 11 | babel-preset-env 12 | browserlist 13 | Browserslist 14 | cli-guides-source 15 | CloudFront 16 | CSP 17 | css-files 18 | Cygwin 19 | DDoS 20 | devDependencies 21 | DevTools 22 | DX 23 | emacs 24 | ember-a11y-testing 25 | ember-auto-import 26 | ember-basic-dropdown 27 | ember-bootstrap 28 | ember-cli 29 | ember-cli-addon-docs 30 | ember-cli-build 31 | ember-cli-deploy 32 | ember-cli-github-pages 33 | ember-cli-less 34 | ember-cli-mirage 35 | ember-cli-sass 36 | ember-cli-sri 37 | ember-cli-typescript 38 | ember-concurrency 39 | ember-d3 40 | ember-data 41 | ember-intl 42 | ember-lifeline 43 | ember-mode 44 | ember-moment 45 | ember-oauth2 46 | ember-paper 47 | ember-power-select 48 | ember-simple-auth 49 | ember-test-selectors 50 | filesystem 51 | foundational 52 | GoToAnything 53 | Heroku 54 | Homebrew 55 | http-to-https 56 | in-repo 57 | integrations 58 | Integrations 59 | Intellij-emberjs 60 | JetBrains 61 | JIT 62 | js-files 63 | linters 64 | LiveReload 65 | MacOS 66 | MELPA 67 | minibuffer 68 | minifer-specific 69 | minifiers 70 | monorepo 71 | namespacing 72 | natively 73 | nfs 74 | nginx 75 | NiM 76 | NTFS 77 | PowerShell 78 | pnpm 79 | pre-made 80 | Pre-Octane 81 | preloading 82 | prepend 83 | preprocessed 84 | preprocessing 85 | production-env 86 | Quickstart 87 | REPL 88 | repo 89 | rerender 90 | retext-spell 91 | runtime 92 | scalable 93 | Set-ExecutionPolicy 94 | somepackage 95 | SRI 96 | ssl 97 | StateManager 98 | Subresource 99 | toolchain 100 | toolset 101 | torii 102 | transpilation 103 | UAC 104 | URL-safe 105 | util 106 | VirtualBox 107 | VM 108 | VMware 109 | WebStorm 110 | Webstorm's 111 | workspaces 112 | WSL 113 | -------------------------------------------------------------------------------- /.netlifyheaders: -------------------------------------------------------------------------------- 1 | /*/ 2 | Cache-Control: public, max-age=3600 3 | 4 | /content/* 5 | Cache-Control: public, max-age=3600 6 | 7 | /assets/* 8 | Cache-Control: public, max-age=31536000 9 | -------------------------------------------------------------------------------- /.netlifyredirects: -------------------------------------------------------------------------------- 1 | / /release/ 2 | /* /_empty.html 404 3 | http://ember-cli-guides.netlify.com/* https://cli.emberjs.com/:splat 301! 4 | -------------------------------------------------------------------------------- /.node-version: -------------------------------------------------------------------------------- 1 | 20.11.0 2 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | # unconventional js 2 | /blueprints/*/files/ 3 | /vendor/ 4 | 5 | # compiled output 6 | /dist/ 7 | /tmp/ 8 | 9 | # dependencies 10 | /bower_components/ 11 | /node_modules/ 12 | 13 | # misc 14 | /coverage/ 15 | !.* 16 | .eslintcache 17 | 18 | # ember-try 19 | /.node_modules.ember-try/ 20 | /bower.json.ember-try 21 | /package.json.ember-try 22 | -------------------------------------------------------------------------------- /.prettierrc.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = { 4 | singleQuote: true, 5 | }; 6 | -------------------------------------------------------------------------------- /.remarkignore: -------------------------------------------------------------------------------- 1 | CONTRIBUTING.md 2 | README.md 3 | -------------------------------------------------------------------------------- /.remarkrc.js: -------------------------------------------------------------------------------- 1 | // .remarkrc.js 2 | /* eslint-env node */ 3 | const unified = require('unified'); 4 | const read = require('fs').readFileSync; 5 | const ember = require('ember-dictionary'); 6 | 7 | exports.plugins = [ 8 | [ 9 | require('remark-retext'), 10 | unified().use({ 11 | plugins: [ 12 | [require('retext-contractions'), { straight: true }], 13 | require('retext-english'), 14 | require('retext-indefinite-article'), 15 | require('retext-repeated-words'), 16 | require('retext-syntax-urls'), 17 | [ 18 | require('retext-spell'), 19 | { 20 | dictionary: ember, 21 | personal: read('./.local.dic'), 22 | }, 23 | ], 24 | ], 25 | }), 26 | ], 27 | 'remark-preset-lint-consistent', 28 | 'remark-preset-lint-recommended', 29 | ['remark-lint-list-item-indent', 'space'], 30 | ]; 31 | -------------------------------------------------------------------------------- /.template-lintrc.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = { 4 | extends: 'recommended', 5 | }; 6 | -------------------------------------------------------------------------------- /.watchmanconfig: -------------------------------------------------------------------------------- 1 | { 2 | "ignore_dirs": ["tmp", "dist"] 3 | } 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | We would love to have your help with writing the next version of the Ember CLI guides! As a work-in-progress, semi-greenfield project, it has different guidelines than other documentation projects. Once the project reaches MVP, these guidelines will change. Our target for MVP is the end of 2018. 4 | 5 | ## Ways to contribute 6 | 7 | Developers of all knowledge and experience levels are invited to help out. Here are ways to contribute: 8 | 9 | - Write new content 10 | - Migrate content over from [ember-cli.com](https://ember-cli.com/). Source code is [here](https://github.com/ember-cli/ember-cli.github.io) 11 | - Help review Pull Requests 12 | - Add comments to Markdown files with tips, resources, and notes to help others figure out what to write 13 | 14 | **Note on respecting copyright** - It is okay to copy/paste content over from ember-cli.com. It is _not_ okay to copy and paste content that you didn't write that came from blog posts, articles, tutorials, etc. whether paid or free. Exceptions are if the license allows it (please link to it in your PR) or you have written permission of the author via a comment on an issue in this repo. 15 | 16 | ## How to get started 17 | 18 | 1. See the [Quest issue](https://github.com/ember-learn/cli-guides-source/issues/3) for a list of tasks that need help. Add a comment indicating which issue you can help with, then open an issue with the name of that task. Any Q&A for the task should go there. Contributors are encouraged to work in pairs. 19 | 2. Read through the Styleguide below 20 | 3. Open a Pull Request as soon as you'd like some feedback. This project aims to be "fast and good enough" rather than slower and perfect. Upon reaching MVP, a final pass will be made to polish content. 21 | 4. Expect at least one round of revisions based on feedback from others 22 | 23 | If you volunteer for a section but are not able to make progress, please speak up so that others may pick up where you left off. Issues that are inactive without response for 3 weeks may be opened up to new contributors. 24 | 25 | ## Leaving comments for other writers 26 | 27 | This Guide is a team project! If you have an idea of the content 28 | that should be in a particular section, some useful resources on 29 | the topic, or even some incomplete explanations, you can add 30 | them as comments in the markdown. This is highly encouraged! We'll strip out comments when we reach MVP. 31 | 32 | ## Styleguide 33 | 34 | 35 | ### Code Blocks 36 | 37 | JavaScript and Handlebars files should follow the [Ember.js styleguide](https://github.com/emberjs/ember.js/blob/master/STYLEGUIDE.md). 38 | 39 | Extending on these rules: 40 | 41 | - Prefer arrow syntax (except for when scope matters, like computed properties. CPs should be noted that they can’t use arrow functions) 42 | - No `var`. Only `const` and `let` for variable declarations 43 | - Use brace expansion for imports, i.e. import { a, b } from @ember/somepackage and use the same name as is used in the API docs 44 | - Links to the API docs should point to the `/release/` version 45 | - Whenever possible, choose semi-generic heading titles, so that as Ember grows and changes, we can keep using them. 46 | 47 | ### Writing 48 | 49 | When in doubt, test your writing in [http://www.hemingwayapp.com/](http://www.hemingwayapp.com/) 50 | 51 | #### Tone 52 | 53 | Write in a welcoming, approachable way. Think of how you would explain something out loud. That’s the preferred tone - conversational and readable. Short sentences are good. Remember that many developers, this is their first framework and English is not their first language. 54 | 55 | #### Audience of beginners 56 | 57 | The audience is a developer who knows enough to have built a simple HTML/JavaScript (or JQuery) app. Explanations should appeal to both developers who are learning Ember as their first framework, but not be useless to people who know another framework. 58 | 59 | #### Scope 60 | 61 | Give enough information to form the mental-models and show how things are connected. Ask yourself, what does someone need to know about this to build the MVP of their first app at work? How would I explain this to a Junior Developer in their first week at my workplace? Remember that the API docs should serve as the in-depth explanations. If the API docs are insufficient, PR there. 62 | 63 | #### First person plural voice 64 | 65 | Avoid voice altogether whenever you can. When some voice is needed, use first person plural (“we”, “our”, “let’s”) 66 | 67 | 68 | - Needs revision: “There is an entire ecosystem of adapters that allow our Ember app to talk to different types of servers…” 69 | - Better: “There is an entire ecosystem of adapters that allow our Ember app to talk to different types of servers …” 70 | - Best: “There is an entire ecosystem of adapters that allows Ember apps to talk to different types of servers …” 71 | 72 | #### Inclusive language 73 | 74 | “They/Them” is used in place of him/he/she/her/etc. Do not use gender in code examples. Avoid terms like “just, simply, obviously” etc. 75 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Ember Learning Team 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![This project uses GitHub Actions for continuous integration.](https://github.com/ember-learn/cli-guides/workflows/CI/badge.svg)](https://github.com/ember-learn/cli-guides/actions?query=workflow%3ACI) 2 | 3 | # Ember CLI guides 4 | 5 | This repository holds the guides and tutorials for the [Ember CLI](https://github.com/ember-cli/ember-cli), a powerful tool that helps you create, develop, and build an Ember app. 6 | 7 | To contribute to the API documentation itself, which lists properties and methods used by addons and apps, instead visit [Ember CLI](https://github.com/ember-cli/ember-cli), where the API docs are managed as code comments within the codebase. 8 | 9 | This project replaces, updates, and adds to the content historically hosted at [https://ember-cli.com/](https://ember-cli.com/). 10 | 11 | Looking for repositories for the other parts of [emberjs.com](https://emberjs.com)? 12 | Check out 13 | [guides-source](https://github.com/ember-learn/guides-source), 14 | [website](https://github.com/emberjs/website), 15 | [ember-api-docs](https://github.com/ember-learn/ember-api-docs), 16 | [super-rentals tutorial](https://github.com/ember-learn/super-rentals), 17 | [statusboard](https://github.com/ember-learn/statusboard), 18 | [deprecation-app](https://github.com/ember-learn/deprecation-app), 19 | and [styleguide](https://github.com/ember-learn/ember-styleguide). 20 | 21 | 22 | ## Prerequisites 23 | 24 | You will need the following things properly installed on your computer. 25 | 26 | * [Git](https://git-scm.com/) 27 | * [Node.js](https://nodejs.org/) (with npm) 28 | * [Ember CLI](https://ember-cli.com/) 29 | * [Google Chrome](https://google.com/chrome/) 30 | 31 | ## Local Development 32 | 33 | The Ember CLI Guides is a normal Ember application, so if you want to run it locally you follow the standard steps: 34 | 35 | * Clone this repository 36 | * `cd cli-guides-source` 37 | * `npm install` 38 | * `npm start` 39 | * Visit your app at [http://localhost:4200](http://localhost:4200). 40 | 41 | _Note:_ If you are developing in any online editor environment like [codesandbox.io](https://codesandbox.io) or [gitpod.io](https://gitpod.io), then you may not able to serve the application properly because of FastBoot's domain configurations. In such cases, you can disable fastboot in development mode by serving the ember app using `FASTBOOT_DISABLED=true ember serve` command. 42 | 43 | If you then edit the Markdown files located in the `guides/` folder your 44 | application should live-update with the content changes. 45 | 46 | To run the tests you can run `npm run lint:md` and `npm test` in your terminal. `npm run lint:md` will spellcheck and enforce consistency in the Markdown files. `npm test` will run Ember tests that have been setup and also scripts that check the Markdown 47 | files links. 48 | 49 | Markdown linting (`lint:md`) must pass. Otherwise, it will fail in CI (continuous integration). Spellchecking uses a custom [ember-dictionary](https://github.com/maxwondercorn/ember-dictionary) with words and terms common to the Ember community, such as `SemVer`. Words and terms that are associated with a specific guide can be placed in the `.local.dic` dictionary file. Create a pull request if a word needs to be added to `ember-dictionary`. 50 | 51 | ## How this app works 52 | 53 | The guides content is in the form of Markdown files in the [guides](https://github.com/ember-learn/cli-guides/tree/main/guides) directory. An Ember app processes and serves the Markdown files. If you look at the `app` directory, you'll see there's not much in it! That's because most of the work is done through a dependency on [guidemaker](https://sea-region.github.com/empress/guidemaker), a static site generator created in Ember. 54 | 55 | The API docs are built from the `ember-cli` source code. Deployment and hosting details can be found in the [`ember-cli.github.io`](https://github.com/ember-learn/ember-cli.github.io) repository. 56 | 57 | ## Contributing 58 | 59 | Do you know a thing or two about the CLI or addons? Do you _wish_ you knew a thing or do? We'd love to have your help with writing or reviewing to make sure that content is helpful to all knowledge levels. To learn more about the motivation for this, read this [RFC](https://github.com/jenweber/rfcs-1/blob/cli-guides/active/0000-cli-guides.md). If you're new to writing Markdown, follow [this cheat sheet](https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf). 60 | 61 | Overall project status and tasks that need help are tracked in [this Quest issue](https://github.com/ember-learn/cli-guides-source/issues/3). Have a read through that and the [CONTRIBUTING.md](CONTRIBUTING.md) file in order to get started. 62 | 63 | 64 | ### Adding more things to the table of contents 65 | 66 | See `pages.yaml` in the cli-guides-source. Whatever has a URL of `index` will be shown for the top level path, like `/tutorial/`. There must be an `index.md` under each topic. 67 | 68 | ### Deploying 69 | 70 | The app is continuously deployed to Netlify when a pull request is merged and passes continuous integration. 71 | -------------------------------------------------------------------------------- /app/app.js: -------------------------------------------------------------------------------- 1 | import Application from '@ember/application'; 2 | import Resolver from 'ember-resolver'; 3 | import loadInitializers from 'ember-load-initializers'; 4 | import config from '@ember-learn/cli-guides/config/environment'; 5 | 6 | export default class App extends Application { 7 | modulePrefix = config.modulePrefix; 8 | podModulePrefix = config.podModulePrefix; 9 | Resolver = Resolver; 10 | } 11 | 12 | loadInitializers(App, config.modulePrefix); 13 | -------------------------------------------------------------------------------- /app/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | {{content-for "head"}} 10 | 11 | 12 | 13 | 14 | {{content-for "head-footer"}} 15 | 16 | 17 | {{content-for "body"}} 18 | 19 | 20 | 21 | 22 | {{content-for "body-footer"}} 23 | 24 | 25 | -------------------------------------------------------------------------------- /app/router.js: -------------------------------------------------------------------------------- 1 | import EmberRouter from '@ember/routing/router'; 2 | import config from '@ember-learn/cli-guides/config/environment'; 3 | 4 | export default class Router extends EmberRouter { 5 | location = config.locationType; 6 | rootURL = config.rootURL; 7 | } 8 | 9 | Router.map(function () {}); 10 | -------------------------------------------------------------------------------- /app/styles/app.css: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ember-learn/cli-guides/5741a2852fb128d7c13715fd9fd75a310a97b740/app/styles/app.css -------------------------------------------------------------------------------- /config/ember-cli-update.json: -------------------------------------------------------------------------------- 1 | { 2 | "schemaVersion": "1.0.0", 3 | "packages": [ 4 | { 5 | "name": "ember-cli", 6 | "version": "3.28.6", 7 | "blueprints": [ 8 | { 9 | "name": "app", 10 | "outputRepo": "https://github.com/ember-cli/ember-new-output", 11 | "codemodsSource": "ember-app-codemods-manifest@1", 12 | "isBaseBlueprint": true, 13 | "options": [ 14 | "--no-welcome" 15 | ] 16 | } 17 | ] 18 | } 19 | ] 20 | } 21 | -------------------------------------------------------------------------------- /config/environment.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = function (environment) { 4 | let ENV = { 5 | modulePrefix: '@ember-learn/cli-guides', 6 | environment, 7 | rootURL: '/', 8 | locationType: 'trailing-history', 9 | historySupportMiddleware: true, 10 | 11 | EmberENV: { 12 | FEATURES: { 13 | // Here you can enable experimental features on an ember canary build 14 | // e.g. EMBER_NATIVE_DECORATOR_SUPPORT: true 15 | }, 16 | EXTEND_PROTOTYPES: { 17 | // Prevent Ember Data from overriding Date.parse. 18 | Date: false, 19 | }, 20 | }, 21 | 22 | APP: { 23 | // Here you can pass flags/options to your application instance 24 | // when it is created 25 | }, 26 | 27 | 'ember-meta': { 28 | description: 'Ember CLI Guides', 29 | }, 30 | 31 | guidemaker: { 32 | title: 'Ember CLI Guides', 33 | sourceRepo: 'https://github.com/ember-learn/cli-guides', 34 | sourceBranch: 'main', 35 | }, 36 | 37 | 'ember-showdown-shiki': { 38 | theme: 'github-dark', 39 | languages: [ 40 | 'bash', 41 | 'css', 42 | 'http', 43 | 'javascript', 44 | 'json', 45 | 'json5', 46 | 'ruby', 47 | 'scss', 48 | 'yaml', 49 | 'typescript', 50 | 'glimmer-js', 51 | 'glimmer-ts', 52 | 'handlebars', 53 | ], 54 | }, 55 | }; 56 | 57 | if (environment === 'development') { 58 | // ENV.APP.LOG_RESOLVER = true; 59 | // ENV.APP.LOG_ACTIVE_GENERATION = true; 60 | // ENV.APP.LOG_TRANSITIONS = true; 61 | // ENV.APP.LOG_TRANSITIONS_INTERNAL = true; 62 | // ENV.APP.LOG_VIEW_LOOKUPS = true; 63 | } 64 | 65 | if (environment === 'test') { 66 | // Testem prefers this... 67 | ENV.locationType = 'none'; 68 | 69 | // keep test console output quieter 70 | ENV.APP.LOG_ACTIVE_GENERATION = false; 71 | ENV.APP.LOG_VIEW_LOOKUPS = false; 72 | 73 | ENV.APP.rootElement = '#ember-testing'; 74 | ENV.APP.autoboot = false; 75 | } 76 | 77 | if (environment === 'production') { 78 | // here you can enable a production-specific feature 79 | } 80 | 81 | return ENV; 82 | }; 83 | -------------------------------------------------------------------------------- /config/fastboot.js: -------------------------------------------------------------------------------- 1 | module.exports = function () { 2 | return { 3 | buildSandboxGlobals(defaultGlobals) { 4 | return Object.assign({}, defaultGlobals, { 5 | atob: atob, 6 | }); 7 | }, 8 | }; 9 | }; 10 | -------------------------------------------------------------------------------- /config/optional-features.json: -------------------------------------------------------------------------------- 1 | { 2 | "application-template-wrapper": false, 3 | "default-async-observers": true, 4 | "jquery-integration": false, 5 | "template-only-glimmer-components": true 6 | } 7 | -------------------------------------------------------------------------------- /config/targets.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const browsers = [ 4 | 'last 1 Chrome versions', 5 | 'last 1 Firefox versions', 6 | 'last 1 Safari versions', 7 | ]; 8 | 9 | // Ember's browser support policy is changing, and IE11 support will end in 10 | // v4.0 onwards. 11 | // 12 | // See https://deprecations.emberjs.com/v3.x#toc_3-0-browser-support-policy 13 | // 14 | // If you need IE11 support on a version of Ember that still offers support 15 | // for it, uncomment the code block below. 16 | // 17 | // const isCI = Boolean(process.env.CI); 18 | // const isProduction = process.env.EMBER_ENV === 'production'; 19 | // 20 | // if (isCI || isProduction) { 21 | // browsers.push('ie 11'); 22 | // } 23 | 24 | module.exports = { 25 | browsers, 26 | }; 27 | -------------------------------------------------------------------------------- /ember-cli-build.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const EmberApp = require('ember-cli/lib/broccoli/ember-app'); 4 | 5 | module.exports = function (defaults) { 6 | let app = new EmberApp(defaults, { 7 | fingerprint: { 8 | extensions: ['js', 'css', 'map'], 9 | }, 10 | }); 11 | 12 | // Use `app.import` to add additional libraries to the generated 13 | // output files. 14 | // 15 | // If you need to use different assets in different 16 | // environments, specify an object as the first parameter. That 17 | // object's keys should be the environment name and the values 18 | // should be the asset to use in that environment. 19 | // 20 | // If the library that you are including contains AMD or ES6 21 | // modules that you would like to import into your application 22 | // please specify an object with the list of modules as keys 23 | // along with the exports of each module as its value. 24 | 25 | return app.toTree(); 26 | }; 27 | -------------------------------------------------------------------------------- /guides/advanced-use/asset-compilation.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | When working on an Ember app, sometimes you may want to customize how certain kinds of assets are handled. This is referred to as "asset compilation." 4 | 5 | For information on stylesheets, please see the dedicated section, [Stylesheet compilation](../stylesheets/) 6 | 7 | ## Raw Assets 8 | 9 | To include images, fonts, or other assets, place them in the `public/assets` directory. 10 | 11 | For example, if you place `logo.png` in `public/assets/images`, you can reference it in 12 | templates with `assets/images/logo.png` or in stylesheets with 13 | `url('/assets/images/logo.png')`. 14 | 15 | In production builds, these assets are [fingerprinted](#fingerprintingandcdnurls), but 16 | all references are also automatically updated. This functionality comes from 17 | [broccoli-asset-rev](https://github.com/rickharrison/broccoli-asset-rev). Be sure to check out 18 | all the options and usage notes. 19 | 20 | ## JS transpiling 21 | 22 | Ember CLI automatically transpiles future JavaScript (ES6/ES2015, ES2016 and beyond) into standard ES5 23 | JavaScript that runs on every browser using [Babel JS](https://babeljs.io) with the [Ember CLI Babel](https://github.com/babel/ember-cli-babel) addon. 24 | 25 | Internally, Ember CLI Babel uses `babel-preset-env`, which figures out which parts of your code 26 | need to be transpiled to ES5 by **analyzing your project's browser support targets**. A `target` is a special keyword 27 | that maps to a [browserlist](https://github.com/ai/browserslist) support rule. These are defined in your 28 | `config/targets.js` file, which [Ember CLI generates](https://github.com/ember-cli/ember-cli/blob/master/blueprints/app/files/config/targets.js) like so: 29 | 30 | 31 | ```javascript {data-filename=config/targets.js} 32 | 'use strict'; 33 | 34 | const browsers = [ 35 | 'last 1 Chrome versions', 36 | 'last 1 Firefox versions', 37 | 'last 1 Safari versions' 38 | ]; 39 | 40 | const isCI = !!process.env.CI; 41 | const isProduction = process.env.EMBER_ENV === 'production'; 42 | 43 | if (isCI || isProduction) { 44 | browsers.push('ie 11'); 45 | } 46 | 47 | module.exports = { 48 | browsers 49 | }; 50 | ``` 51 | 52 | (If these values look familiar, they're the same exact values used by the popular [Autoprefixer](https://github.com/postcss/autoprefixer) project. Autoprefixer has an [online version](https://goonlinetools.com/autoprefixer/) that allows you to enter your non-prefixed CSS and gives you a prefix-added CSS.) 53 | 54 | If you need more fine-grained customization over the way that `babel-preset-env` transforms your code, 55 | set any of the [babel-preset-env options](https://babeljs.io/docs/en/babel-preset-env.html#options) on your application's `babel` hash in `ember-cli-build.js`. 56 | 57 | For example, if you wanted to explicitly exclude generator function transpilation from your 58 | output, your configuration would look like this: 59 | 60 | ```javascript {data-filename=ember-cli-build.js} 61 | /* eslint-env node */ 62 | 'use strict'; 63 | const EmberApp = require('ember-cli/lib/broccoli/ember-app'); 64 | 65 | module.exports = function(defaults) { 66 | let app = new EmberApp(defaults, { 67 | babel: { 68 | exclude: [ 69 | 'transform-regenerator', 70 | // ...more options 71 | ] 72 | } 73 | }); 74 | 75 | //... 76 | return app.toTree(); 77 | }; 78 | ``` 79 | 80 | As of Version 2.13, Ember CLI uses Babel 6.X for transpilation. Ember CLI versions prior to 2.13 use Babel Babel 5.X, and you can check its documentation for a comprehensive list of [all available transformations](https://github.com/babel/babel.github.io/blob/5.0.0/docs/usage/transformers/index.md) and [options](https://github.com/babel/babel.github.io/blob/5.0.0/docs/usage/options.md). 81 | 82 | ## Source maps 83 | 84 | Ember CLI supports producing source maps for your concatenated and minified JS source files. 85 | 86 | Source maps are configured by the EmberApp `sourcemaps` option, and 87 | are disabled in production by default. Pass `sourcemaps: {enabled: true}` to your EmberApp constructor to enable source maps for JavaScript. Use the `extensions` option to add other formats, such as CSS: `{extensions: ['js', 'css']}`. JS is supported out-of-the-box. CSS is not currently supported. For other source formats, refer to their addons. 88 | 89 | Default `ember-cli-build.js`: 90 | 91 | ```javascript {data-filename=ember-cli-build.js} 92 | 'use strict'; 93 | 94 | const EmberApp = require('ember-cli/lib/broccoli/ember-app'); 95 | 96 | module.exports = function(defaults) { 97 | let app = new EmberApp(defaults, { 98 | // Add options here 99 | }); 100 | 101 | // Use `app.import` to add additional libraries to the generated... 102 | 103 | return app.toTree(); 104 | }; 105 | }; 106 | ``` 107 | 108 | ## Minifying 109 | 110 | Compiled css-files are minified by `ember-cli-clean-css`, or other registered CSS minifiers, 111 | if they are installed locally. You can pass minifer-specific options to them using 112 | the `minifyCSS:options` object in your ember-cli-build. Minification is enabled by 113 | default in the production-env and can be disabled using the `minifyCSS:enabled` 114 | switch. 115 | 116 | Similarly, the js-files are minified with `ember-cli-terser` 117 | in the production environment by default. You can pass custom options to the minifier via the 118 | `ember-cli-terser:options` object in your ember-cli-build. To enable or disable JS minification 119 | you may supply a boolean value for `ember-cli-terser:enabled`. 120 | 121 | For example, to disable minifying of CSS and JS, add in `ember-cli-build.js`: 122 | 123 | ```javascript {data-filename=ember-cli-build.js} 124 | const EmberApp = require('ember-cli/lib/broccoli/ember-app'); 125 | 126 | module.exports = function(defaults) { 127 | let app = new EmberApp(defaults, { 128 | 'ember-cli-terser': { 129 | enabled: false 130 | }, 131 | minifyCSS: { 132 | enabled: false 133 | } 134 | }); 135 | 136 | //... 137 | return app.toTree(); 138 | }; 139 | ``` 140 | 141 | More details on available options to customize JavaScript minification can be found in 142 | [`ember-cli-terser` docs](https://github.com/ember-cli/ember-cli-terser#options). 143 | 144 | ***Note**: `ember-cli-uglify` was renamed to `ember-cli-terser` with the 4.0.0 release. This change is part of Ember CLI's default blueprint since 3.21.1. Projects still using `ember-cli-uglify` can find its configuration options in the [`ember-cli-uglify` docs](https://github.com/ember-cli/ember-cli-terser/tree/v3.0.0.).* 145 | 146 | ### Exclude from minification 147 | 148 | Some files should be excluded from minification, such as copied-and-pasted third-party scripts that are already minified. 149 | 150 | To exclude assets from `dist/assets` from being minified, one can pass options for 151 | [broccoli-uglify-sourcemap](https://github.com/ef4/broccoli-uglify-sourcemap) like so: 152 | 153 | ```javascript {data-filename=ember-cli-build.js} 154 | const EmberApp = require('ember-cli/lib/broccoli/ember-app'); 155 | 156 | module.exports = function(defaults) { 157 | let app = new EmberApp(defaults, { 158 | minifyJS: { 159 | options: { 160 | exclude: ["**/vendor.js"] 161 | } 162 | } 163 | }); 164 | 165 | //... 166 | return app.toTree(); 167 | }; 168 | ``` 169 | 170 | This would exclude the resulting `vendor.js` file from being minified. 171 | 172 | ## Fingerprinting and CDN URLs 173 | 174 | Fingerprinting is done using the addon 175 | [broccoli-asset-rev](https://github.com/rickharrison/broccoli-asset-rev) 176 | (which is included by default). 177 | 178 | When the environment is production (e.g. `ember build --environment=production`), 179 | the addon will automatically fingerprint your JS, CSS, PNG, JPG, and GIF assets 180 | by appending a md5 checksum to the end of their filename 181 | (e.g. `assets/yourapp-9c2cbd818d09a4a742406c6cb8219b3b.js`). In addition, your 182 | HTML, JS, and CSS files will be re-written to include the new name. There are 183 | a few options you can pass into `EmberApp` in your `ember-cli-build.js` to customize 184 | this behavior. 185 | 186 | * `enabled` - Default: `app.env === 'production'` - Boolean. Enables fingerprinting 187 | if true. **True by default if current environment is production.** 188 | * `exclude` - Default: `[]` - An array of strings. If a filename contains any 189 | item in the exclude array, it will not be fingerprinted. 190 | * `ignore` - Default: `[]` - An array of strings. If a filename contains any item in the 191 | ignore array, the contents of the file will not be processed for fingerprinting. 192 | * `extensions` - Default: `['js', 'css', 'png', 'jpg', 'gif', 'map']` - The file types 193 | to add md5 checksums. 194 | * `prepend` - Default: `''` - A string to prepend to all of the assets. Useful 195 | for CDN URLs like `https://subdomain.cloudfront.net/` 196 | * `replaceExtensions` - Default: `['html', 'css', 'js']` - The file types to 197 | replace source code with new checksum file names. 198 | * `customHash` - When specified, this is appended to fingerprinted filenames instead 199 | of the md5. Pass `null` to suppress the hash, which can be useful when using `prepend`. 200 | 201 | As an example, this `ember-cli-build` will exclude any file in the fonts/169929 202 | directory as well as add a CloudFront domain to each fingerprinted asset. 203 | 204 | ```javascript {data-filename=ember-cli-build.js} 205 | const EmberApp = require('ember-cli/lib/broccoli/ember-app'); 206 | 207 | module.exports = function(defaults) { 208 | let app = new EmberApp({ 209 | fingerprint: { 210 | exclude: ['fonts/169929'], 211 | prepend: 'https://subdomain.cloudfront.net/' 212 | } 213 | }); 214 | 215 | //... 216 | return app.toTree(); 217 | }; 218 | ``` 219 | 220 | The end result will turn 221 | 222 | ```html 223 | 32 | 33 | 34 | 35 | 36 | 37 | {{content-for "body-footer"}} 38 | {{content-for "test-body-footer"}} 39 | 40 | 41 | -------------------------------------------------------------------------------- /tests/test-helper.js: -------------------------------------------------------------------------------- 1 | import Application from '@ember-learn/cli-guides/app'; 2 | import config from '@ember-learn/cli-guides/config/environment'; 3 | import { setApplication } from '@ember/test-helpers'; 4 | import { start } from 'ember-qunit'; 5 | import * as QUnit from 'qunit'; 6 | import { setup } from 'qunit-dom'; 7 | 8 | setup(QUnit.assert); 9 | 10 | setApplication(Application.create(config.APP)); 11 | 12 | start(); 13 | --------------------------------------------------------------------------------