DEV Community: Ember Ocean

Debugging an Ember Octane App

Robin Philip Thomas — Mon, 07 Dec 2020 07:36:18 +0000

So you have been asked to fix a bug or to explore functionality in an Ember app. Have a humungous code-base and have no idea where to start! Well, you are in luck as I'll be showing you some tips on common debugging and reverser engineering ways in Ember world.

Step 0

For debugging with ease, make sure sourcemaps are generated for your builds. If they are not being generated, then go to ember-cli-build.js and pass:

  sourcemaps: {
   enabled: true
  },

as options to EmberApp() function.

With this enabled, a special kind of file (aka sourcemaps) will be generated along with the bundled output, which the browser can use to understand the original source code you wrote from the bundled output.

While there are many ways to debug an ember app, we will be mostly looking at debugging with the help of ember inspector in this blog.

Finding the component which has the bug

Let's say you are debugging this page: www.emberobserver.com/code-search.

And you wanna figure out how the code search section is built or debug it.

To do that you have to find out what component is used to render the code search input box dom. But how do you find which component has the code for it?

The easiest way to find the respective component files is by using the Ember Inspector

Steps to install the extension for chrome or firefox can be found here.

Now with the extension installed, refresh the page and open dev-tools. You will see that a new tab named ember has come in the dev-tools status bar. Click on it!

Now click on the Components tab there

You will see a list of components used on the page.
Click on the mouse with a square in the background icon.

Now move your mouse to the code search dom element and click on it.

The Ember inspector should have highlighted on the component used for rendering that particular code search section dom.

From what we can see, it seems to be a component named CodeSearch. To confirm if there exists a component in that name, let's search the ember-observer code-base for files which contains the name code-search.

And voila there seem to files:
github.com/emberobserver/client/blob/master/app/components/code-search.js and github.com/emberobserver/client/blob/master/app/components/code-search.hbs present.

On the right side on the pane, you will get to see all the properties used in the component.

Hover over one of the properties and click on the $E text to inspect the prop value in the console.

Debugging the component

Now that you know how to find what component is being used in a place, let me show you how to add debuggers or logger statements in the component code.

The component mainly consists of two files:
the component.js file and
the template.hbs file

debugging the component.js

Debugging the component.js file is same as debugging any other javascript file.
You have debugger statement to stop the code execution at that particular line and console.log(variable name) to log variable values to the console.

debugging the template.hbs

In the template file as well you have the ability to add debuggers and log statement. But using them is slightly different.

You have helper methods to add debuggers and log statement here.

To add breakpoints in the template, you write the {{debugger}} statement.

Once the execution stops in a template breakpoint,
you can use the get(<path>) method in the console to get values of properties used in the template. For example, you can type get(this.name) or get(@value) to print those property values to the console.

To log property values used in templates to the console, use the {{log prop_name}} helper.

Finding the route and controller files for a page.

As you saw in the last section, finding the component files was easy peasy. But most of our data and logic mostly would likely reside in the route and controller files respectively.

One way to find the route and controller files is by looking at the URL of the page you are in. And then checking your router.js file to find which route and controllers may be matched for the URL.

But is there an easier way!.

Well, there is, thanks to ember inspector once again.

In ember inspector, you do get a routes tab which shows all the routes and respective controllers available.

What I usually like to do is enable Current Route only filter so that we only see the routes and controller used in the current page we are on.

This is particularly handy in debugging pages which have nested routes involved in rendering it.

Debugging ember data

While working with ember-data one thing I do keep open is the data tab in ember inspector. It shows the ember-data models available and the records stored in it.

The pane even has filters like New and Modified, where New shows ember-data records that have been newly created and not saved to the backend yet. And modified are saved records that have properties modified in the client and not synced up with the backend.

Extra tip

Measuring render performance

While building complex pages and components, I do recommend looking at the Render Performance tab in the ember inspector.

It shows the time taken by each component to render on screen.
If the render time is high, one thing you can do is optimise the logic and add loading state UI elements to the component.

I hope this blog post helped you in debugging your ember app with ease.

If you are still stuck…
hop on the Ember Community Discord and post you queries in the #help channel. Hopefully, somebody will be able to help you out.

How to integrate Netlify-CMS with Empress-blog

Robin Philip Thomas — Mon, 07 Dec 2020 07:35:55 +0000

So you use Empress-blog for your blog website. Do you edit and add blogs in local? What if you don't have your personal laptop? Do you then re-create the whole project just to add a new blog post? What if I told you there was a better way!

Wouldn't be great if you could have a CMS for your blog and that too free of cost. Add and Edit blog posts from the browser itself. 🤩

Let me introduce you to Netlify CMS your open source content management for your Git workflow.

OK just show me how!

1) Create a new Empress-blog project

Let's first create a new ember project and convert it into a empress-blog project.

Run the following commands in the terminal, in the folder where you'd like to create the blog.

ember new super-blog
cd super-blog
ember install empress-blog empress-blog-attila-template

It will ask you if you want to update the index.html file and you should say yes 👍

For this tutorial, we will be using the empress-attila-template.

Get to know Empress

In your favourite code editor, open up the code generated, and take a look at the content directory.

You will see that there are multiple Markdown files that represent blog posts. Open one .md file and you will see something like this:

---
title: "Welcome to empress-blog"
image: /images/welcome.jpg
imageMeta:
  attribution:
  attributionLink:
featured: true
authors:
  - ghost
date: Tue Jun 12 2018 18:59:59 GMT+0100 (IST)
tags:
  - getting-started
---

Hey! Welcome to empress-blog, it's great to have you :)

We can see above that each blog post has a title, image, author, body and other properties. We will be recreating this using Netlify CMS.

Similarly, have a look at author and tags folder .md files. We will need them for adding author(s) and tag(s) for your blog posts.

Note: for other global configuration options, check out https://github.com/empress/empress-blog#configuring

Try running in local with npm start and your blog should be live in http://localhost:4200

Great things are working in local. Let's move on to the CMS part.

2) Add Netlify CMS to your site

Update: you don't need to do step 2 anymore. Just ember install empress-blog-netlify-cms and you are good to go. For more details check out https://github.com/MalayaliRobz/empress-blog-netlify-cms.

Let's start giving your blog some superpowers. In the public folder create admin folder with config.yml and index.html files in it.

├── public
     ├── admin
         ├ index.html
         └ config.yml

In your config.yml file paste the following configuration:

backend:
  name: git-gateway
  branch: master
media_folder: 'public/uploads'
public_folder: "/uploads"
collections:
  - name: 'blog'
    label: 'Blog'
    folder: 'content/'
    create: true
    slug: "{% raw %}{{year}}{{month}}{{day}}{{slug}{% endraw %----}"
    fields:
       { name: "title", label: "Title", widget: "string" }
       { name: "image", label: "Image", widget: "image", required: false }
      - name: "imageMeta"
        label: "ImageMeta"
        widget: "object"
        collapsed: true
        fields: 
           { label: "attribution", name: "attribution", widget: "string", default: '', required: false }
           { label: "attributionLink", name: "attributionLink", widget: "string", default: '', required: false }
       { name: "featured", label: "Featured", widget: "boolean", default: true }
       { name: "authors", label: "Authors", widget: "list", default: ["ghost"] }
       { name: "tags", label: "Tags", widget: "list", default: ["new"], required: false }
       { name: "body", label: "Body", widget: "markdown" }
       { label: "Publish Date", name: "date", widget: "datetime", format: "ddd MMM DD YYYY h:mm:ss a"}

  - name: 'author'
    label: 'Author'
    folder: 'author/'
    create: true
    slug: "{% raw %}{{name}}{% endraw %----}"
    fields:
       { name: "name", label: "Name", widget: "string" }
       { name: "id", label: "Id", widget: "string" }
       { name: "image", label: "Image", widget: "image", required: false }
       { name: "cover", label: "Cover", widget: "string", required: false }
       { name: "website", label: "Website", widget: "string", required: false }
       { name: "twitter", label: "Twitter", widget: "string", required: false }
       { name: "facebook", label: "Facebook", widget: "string", required: false }
       { name: "location", label: "Location", widget: "string", required: false }
       { name: "body", label: "Body", widget: "markdown", required: false }

  - name: 'tag'
    label: 'Tag'
    folder: 'tag/'
    create: true
    slug: "{% raw %}{{name}}{% endraw %----}"
    fields:
       { name: "name", label: "Name", widget: "string" }
       { name: "image", label: "Image", widget: "image", required: false }
       { name: "body", label: "Body", widget: "markdown", required: false }

For this tutorial, we will be using git-gateway as our backend for Netlify CMS. More details can be found here.

In your index.html file, paste in the following contents.

<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
  <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</head>
<body>
  <!-- Include the script that builds the page and powers Netlify CMS -->
  <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
</body>
</html>

Some more configuration

While adding users to your CMS, netlify will send them an email with a link to your blog url containing an access token. We need to setup a watch for this and redirect them to the admin page so that netlify can verify them and add them as users.

In index.html file in the app folder. Add <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script> to the tag. Also after the tag add this small script.

  <script>
    if (window.netlifyIdentity) {
      window.netlifyIdentity.on("init", user => {
        if (!user) {
          window.netlifyIdentity.on("login", () => {
            document.location.href = "/admin/";
          });
        }
      });
    }
  </script>

The whole index.html file should look something like this now.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>

    {% raw %}{{content-for "head"}}{% endraw %}

    <link integrity="" rel="stylesheet" href="{% raw %}{{rootURL}}assets/vendor.css{% endraw %}">
    <link integrity="" rel="stylesheet" href="{% raw %}{{rootURL}}assets/super-blog.css{% endraw %}">

    {% raw %}{{content-for "head-footer"}}{% endraw %}
  </head>
  <body>
    {% raw %}{{content-for "body"}}{% endraw %}

    <script src="{% raw %}{{rootURL}}assets/vendor.js{% endraw %}"></script>
    <script src="{% raw %}{{rootURL}}assets/super-blog.js{% endraw %}"></script>

    {% raw %}"{{content-for "body-footer"}}{% endraw %}
  </body>

  <script>
    if (window.netlifyIdentity) {
      window.netlifyIdentity.on("init", user => {
        if (!user) {
          window.netlifyIdentity.on("login", () => {
            document.location.href = "/admin/";
          });
        }
      });
    }
  </script>
</html>

🥳 we are almost done. Just a few more steps.

3) Push to GitHub

It's now time to commit your changes and push to GitHub. The ember new command does in-fact initialise a Git project automatically for you, so you only need to do:

git add .
git commit -m "Initial Commit"
git remote add origin https://github.com/YOUR_USERNAME/NEW_REPO_NAME.git
git push -u origin master

4) Add your repo to Netlify

Go to Netlify and select 'New Site from Git'. Select GitHub and the repository you just pushed to. Click Configure Netlify on GitHub and give access to your repository. Finish the setup by clicking Deploy Site. Netlify will begin reading your repository and starting building your project.

5) Enable Identity and Git Gateway

Netlify's Identity and Git Gateway services allow you to manage CMS admin users for your site without requiring them to have an account with your Git host or commit access on your repo. From your site dashboard on Netlify:

Go to Settings > Identity, and select Enable Identity service.
Under Registration preferences, select Open or Invite only. In most cases, you want only invited users to access your CMS, but if you're just experimenting, you can leave it open for convenience.
If you'd like to allow one-click login with services like Google and GitHub, check the boxes next to the services you'd like to use, under External providers.
Scroll down to Services > Git Gateway, and click Enable Git Gateway. This authenticates with your Git host and generates an API access token. In this case, we're leaving the Roles field blank, which means any logged-in user may access the CMS. For information on changing this, check the Netlify Identity documentation.

6) Accessing the CMS

Your site CMS is now fully configured and ready for login!

If you set your registration preference to "Invite only," invite yourself (and anyone else you choose) as a site user. To do this, select the Identity tab from your site dashboard, and then select the Invite users button. Invited users receive an email invitation with a confirmation link. Clicking the link will take you to your site with a login prompt.

If you left your site registration open, or for return visits after confirming an email invitation, access your site's CMS at yoursite.com/admin/.

After logging-in to the admin page, you should see a screen similar to 👇.

7) Start publishing

It's time to create your first blog post. Click on New Blog button and start adding the title, image and other properties right from the handy interface. When you click Publish, a new commit will be created in your GitHub repo with this format Create Blog “year-month-date-title”.

Then Netlify will detect that there was a commit in your repo and will start rebuilding your project. When your project is deployed you'll be able to see the post you created.

Note: to add tags or authors, click on the respective collection name from the side menu and click on the New button.

Cleanup

It is now safe to remove the default Empress blog posts. You can use the delete entry option available in the CMS.

That's it you have successfully connected your Empress-blog with Netlify CMS. 🎉

Github repo: https://github.com/MalayaliRobz/empress-netlify-cms-starter

For more details on Empress, Netlify CMS check out https://github.com/empress/empress-blog and https://www.netlifycms.org/docs/intro/

Splitting & Migrating your Ember project to a Monorepo

Robin Philip Thomas — Mon, 07 Dec 2020 07:35:38 +0000

Let's imagine a scenario where your ember project is getting fairly large in terms of code size and is getting hard to maintain. What do you do?
You split your code into addons and ember engines right! Monorepo is one good way to maintain these addons and engines without having to maintain multiple repos.

What is a Mono Repo?

Monorepos are simply single repositories with separate npm modules organized into folders.

But why Mono?

So the answer is really simple addons and engines. People love monorepos and the reason is that in such a repository, the code stays in sync with itself.
So when you have multiple modules that live within that repository, the modules stay in sync.
You can have a single PR or even a single commit that is able to orchestrate a change across multiple modules and you can also test these things together.
Also tracking issues is much more convenient when you have modules are co-located inside the same repository.

Some advantages to having a monorepo in ember:

Addon modules dependencies become explicit.
Addon modules have their own test cases.
Addon modules become publishable if you wanna share it among teams.

Before we start: Splitting your project files into engines and addons

Let's say you have an Ember project for a social media site. Let's call it Pacebook.
Among the multiple pages it has, we are interested in the feed page and the chat page.

We are gonna split Pacebook into multiple engine projects.

You could split the root level routes into separate engines or so. Any portion of your project that seems like it can run separately as a standalone app qualifies to be migrated to an engine.

For this project, we are gonna split feed and chat pages into separate engine projects.

Now find common code among these engines and move them to addons. You could also club common CSS as well. Good examples of these would be models, common logic, common css etc.

Here are gonna move some common CSS(design system) and the notifications widget into separate addons.

Now you have something like this:

Pacebook
├── host-app
├── design-system-addon
├── notifications-widget-addon
├── feed-page-engine
└── chat-page-engine

Where Host-app host is your original project and Engine-* are the ones you split.

Now let's get down to business.

Adding yarn workspace

We will be using yarn workspace to create our monorepo.

1) Move your file structure to this kinda layout (not necessary though)

Pacebook
├── host-app
├── addons
│   ├── design-system
│   └── notifications-widget
└── engines
    ├── feed-page
    └── chat-page

2) In your project's root create a package.json file and add these lines

package.json

{
  "private": true,
  "workspaces": ["engines/*", "addons/*"]
}

3) Include engine and addon version's in package.json of the respective apps.
one common trick is to keep engine and addon dependency as '*' in package.json to the host to keep them in the latest version always.

4) Remove all node_modules and yarn-lock or package-lock files from all your folders in the project.

5) run yarn install from the root folder of Pacebook.

Here is a sample repo with yarn workspace

Congrats you have successfully migrated to yarn workspaces!

Adding Lerna to your workspace

Lerna is a tool to help you to maintain your monorepo packages.

Lerna is a tool that optimizes the workflow around managing multi-package repositories with git and npm.

install lerna
run lerna init to create lerna.json file
add these two lines to lerna.json to have it work with yarn workspaces

{  
  ...
  "npmClient": "yarn",
  "useWorkspaces": true,
}

Lerna makes it easy to automate stuff like:

updating package version of addons or engines
run commands in each workspace project in parallel
find when the package had changed since the last release

Full list of lerna commands can be found here.

These might come in handy in your CI where you would wanna run test cases or publish for just the changed engine or addon.

Why not use in-repo addons? (taken from here)

Ember CLI’s original solution for simultaneously developing addons is in-repo addons, which have never required any npm link shenanigans. We have a few reasons for not using them:

In-repo addons cannot have their own test suites. Test files go into the host application. We want our tests to be as decoupled as our application code.
We may want to publish certain addons for use by other Ember applications. In-repo addons are not real NPM packages so they can’t be published on their own.
Similarly, we want to allow teams to escape from the monorepo in the future if it makes sense for their product. Once their code is in a “real” addon with its own dependencies and test suite, they can move the files to another repository without much effort.
Naming is hard—our “real” addons are inside the same git repository, so aren’t they “in-repo” addons? 🤯 To disambiguate the two patterns, we use the term “monorepo addon” for addons in our Yarn workspace

Ok now you have adopted monorepo for you project. Now what?

Unity and move your eslint, prettier, template-list config to the root. That way you have only one config across modules.
Update ember try to take advantage to workspace. Believe me, your try test suit will run much faster now.
While upgrading packages run yarn upgrade-interactive and yarn outdated. You don't have to update packages in multiple repos now. All the packages stay in sync.

Wrapping up

While converting your project to a monorepo gives great advantages, it has some caveats as well such as settings up tooling to get it all working, not all tools may support this file structure, onboarding new member to the team etc...

Sometime you might not even need monorepo especially when something like embroider is on the rise.

You mostly don't need a monorepo when:

your team size is small
project source code is not that big
Can't split code into modules or there is no need

In the end, it mostly up to developers working on a project and weighing up risks and benefits of monorepo for your project.

5 Things to do after building an Ember Addon

Robin Philip Thomas — Mon, 07 Dec 2020 07:35:20 +0000

Congratulation on building your ember addon. But the journey is not done yet. Don't you want your addon to be super easy to maintain and have a lot of collaborators? Follow this 5 steps to get you ember addon to the Next level:

1. Writing docs for your Addon

Having an addon that solves a problem is not good enough sometimes, you need to have good documentation that tells how to use your addon.

Good documentation is always necessary for making your addon a success.

These days, a well-maintained Ember addon should:

Provide interactive demos of their components in the context of an Ember app
Show current and versioned guides, ideally whose content is verified by automated tests
Show current and versioned API documentation derived from structured comments in source code
Make it easy for contributors to correct documentation errors in addition to submitting code fixes

Thankfully we have ember-cli-addon-docs that solves all these documentation problems

It is easy to set-up and gives an awesome out of box layout for your interactive docs.

You can even have your docs along-side you components, so your docs always remain updated. How about that.

2. Having test cases and good test coverage

Your addon may be working fine for now. But what after you have merged a couple of pull-requests. Did any of those mess up any existing functionality?

The only way to test that is to have test cases and run them with each pull-request branch. That way you can be sure your addon's functionality stays intact even after a new feature is added. This is all the more necessary for an open-source addon.

Ember has a robust and easy to learn test framework(Qunit) installed by default that makes writing tests a breeze.

You can also use the interactive docs page from addon-docs to write your test cases on top.

ember-cli-code-coverage is a good tool to get code coverage reports for your code.

3. Speed up your test case runs

Well, you have written your test case and they run fine. But wouldn't you love it if we could make tests run faster... way faster. This becomes more use-full in step 4.

Introducing ember-exam

It provides the ability to randomise, split, parallelise, and load-balance your test suite by adding a more robust CLI command.

4. Running tests for different ember versions

Don't you want your addon to work with different ember versions, and how do you test with different ember versions?

ember-try is the answer to that.

ember can run tests against multiple bower and npm dependencies, such as ember and ember-data.

Coupled with ember exam can make ember try run faster.

This way you can be sure your addon supports ember versions say.. 2.8 - 3.9 just by running the ember try command.

ember try can also be used to run against other dependencies versions as well say, ember-data.

5. Having a CI system

When pull-requests pour in for you open source addon, manually running test cases against them can be a pain in the ass.

Thankfully there are good CI systems that run your test and show the results all inside GitHub.

Some good CI systems are travisci, circleci and both provide free plans to start.

Ember by default comes with travis config files, so you can start using travis out of the box if you wish.

There is also jenkins through which you could build your custom ci server. But you would have to maintain that also !!

You are now ready to open your addon to the wild, I mean the internet of-course
.

There are many other small things you can do to make your addon life easier. But there are the 5 steps I found should be done first.

What do you think, any other things to do, after building your ember addon?