This project is the monorepo for frontend and webview based applications.
Applications are built with Ember.js and managed as a series of pnpm workspaces with lerna workspace tools. The project directory contains several subdirectories that organize our various workspaces by type.
- Engines are contained in the directory
engines/ - Applications are contained in the directory
apps/ - Addons are contained in the directory
addons/ - Tools (custom tooling packages) are contained in the directory
tools/
Using pnpm and Lerna in this way allows us to author multiple applications, libraries and tools that are utilized by each other and maintained together.
MacOS
Setup for All
- If you haven't previously setup the command line tools for OSX, start by installing them by running the following command in the terminal.
xcode-select --install- Clone this repository locally from whichever directory you would like it to be in. For instance if you have a
githubdirectory you mightcd ~/githubfirst before cloning the repository. This will require you to have configured your ssh keys.
git clone [email protected]:prysmex/ember-rrule-generator.gitThis will create a new folder fnb within the current directory containing the project files.
- If your machine does not already have volta, make sure you have it installed. This will ensure that the correct node version is available when within the project.
curl https://get.volta.sh | bash- Install
pnpm
curl -fsSL https://get.pnpm.io/install.sh | sh -- Install dependencies.
pnpm installSetup for Development
There is currently no additional setup needed for developing on the frontend beyond the instructions in setup for all. However, you may find it useful to have ember-cli globally available.
volta install ember-cliYou may also want to install watchman, which can help with many performance situations during the build.
brew install watchmanRunning the Project
Starting an App
pnpm run start:<appName>:localThis will start the development server and launch a browser with the specified app.
If you would like more control over the build, test, and serve commands navigate to the respective
application and utilize the respective commands from within the given repository. This can be especially useful
when debugging or when trying to examine the difference between two versions/commits.
Running Lint & Tests
We run three separate forms of lint checks on our codebase. These checks run in CI on Pull Requests but you can also run them individually via the command line.
These checks are configured in a way
that they run lint on all of the projects within workspaces, but you can choose to switch into an individual project and run the same lint command within it as well. All root commands are in the scripts hash within ./package.json while individual project commands are in their respective package.json files.
- Typescript Compiler Check:
pnpm run lint:typesconfigured by ./.tsconfig.json - Javascript & Typescript Lint:
pnpm run lint:jstsconfigured by ./.eslintrc.js - Handlebars Linting:
pnpm run lint:hbsconfigured by ./.template-lintrc.js
In addition to various browser compatibility and scenario tests, we run two key sets of tests in CI. These commands are similarly found in the scripts hash within ./package.json with corresponding project commands located in respective respective package.json files.
- Production Tests:
pnpm run test:production - Development Tests:
pnpm run test:development
Production and development test scenarios run the same tests; however, production tests exclude tests that check for deprecations, asserts, and dev time checks to ensure our code still functions correctly with these things removed.
Within an individual project you will often want to run the tests specific to that project only. From within that project's directory the same commands above will work; however, they may not give you the fastest feedback, while below options may. Multple ways of running tests are available, below we go into three key distinct methods.
- Accessing tests for any locally served development build.
If you have an application running either via pnpm run start:<app-name>:local or ember serve, then navigating to the /tests url will pull up and run the tests in the browser, allowing you to monitor and debug failures. If the application is serving at localhost:4200, then localhost:4200/tests will give access to the test.
- Launching the tests in their own browser context
From within a project directory:
ember test --serveYou may also be interested in adding the flag --no-launch to prevent auto-launching a custom chrome instance so that you can use and manage the test run within an already open browser.
The flag --disable-live-reload will prevent the test runner from attempting to launch additional browser instances when you've made changes while paused in a debugger.
- Separating out Build and Test
By default ember test --serve will build the application, serve it up, and monitor for changes after which it will rebuild. Sometimes this is undesireable, – for instance when you want to run tests against multiple build specific to SHAs while determining where a problem was introduced – and it also prevents monitoring the terminal for build errors while running tests.
We can separate the build and test serving into two commands within a project directory. First, the build command:
ember build --watch --output-path="./dist"This tells ember to build the app, watch for and rebuild on changes, and put the built assets into the dist directory. If you need to build multiple commits, give them separate output paths!
Next, connect your tests to the pre-built assets.
ember test --serve --path="./dist" --test-port=0This tells the test command to serve up whatever assets are at dist. Whenever the build command rebuilds the test command will detect the changes to the final output, and refreshing your tests page will reflect them. Adding --test-port=0 here tells the test command to pick a random available port to serve on, ensuring we can have multiple test server instances if needed.
Configuring VSCode
Microsoft's Visual Studio Code application (VSCode) is a free and widely used editor for frontend programming (javascript/typescript/html/css/jsx etc.) as well as for some backend languages. Other editors are more specialized for languages like Java (which our backend is written in) so at some point you may want to install a different editor such as IntelliJ if working on backend files.
Download: https://code.visualstudio.com/
Once you have downloaded and launched Visual Studio Code there are a number of plugins/extensions you will want to consider adding and configuring.
- EditorConfig for VS Code | by EditorConfig
- Ember Colorizer and Theme | by ciena-blueplanet
- Eslint | by Microsoft
- GitLens | by GitKraken
- Glint | by TypedEmber
- Live Share, Live Share Audio, and Live Share Extension Pack | by Microsoft
- Prettier - Code formatter | by Prettier
- Prettier for Handlebars | by Ember Tooling
- Unstable Ember Language Server | by lifeart
- Visual Studio IntelliCode | by Microsoft
- Markdown Preview Github Styling | by Matt Bierner
