My Little Tech Life

How to integrate Netlify-CMS with Empress-blog

2020-06-24T01:30:24+00:00

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 super powers. 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: "{{year}}-{{month}}-{{day}}-{{slug}"
    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: "{{name}}"
    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: "{{name}}"
    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 <head> tag. Also after the <body> 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>

    {{content-for "head"}}

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

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

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

    "{{content-for "body-footer"}}
  </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

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

Setting up TailwindCSS with ember with in-build purgeCSS

2020-05-22T00:00:00+00:00

Well, integrating tailwind with ember has become easier than ever. TLDR; as of Tailwind CSS v1.4 tailwind supports built-in PurgeCSS.

Adding tailwindcss to an ember app

Let’s start by creating a new ember app:

ember new your-project --yarn
cd your-project

Install PostCSS

yarn add ember-cli-postcss tailwindcss postcss-import -D

Generate Tailwind configuration file

mkdir app/tailwind
npx tailwind init app/tailwind/config.js --full

Note: you probably don’t want to add –full in a real project.

Add purge config to the top of tailwind config file:

const EmberApp = require('ember-cli/lib/broccoli/ember-app');
const isProduction = EmberApp.env() === 'production';

module.exports = {
  purge: {
    enabled: isProduction,
    content: [
    './app/index.html',
    './app/templates/**/*.hbs',
    './app/components/**/*.hbs'
    ]
  },
....

These settings will make sure that you don’t ship any unwanted tailwind CSS to production build. More info here

Update build pipeline to include plugins

// ember-cli-build.js
'use strict';

const EmberApp = require('ember-cli/lib/broccoli/ember-app');

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    postcssOptions: {
      compile: {
        plugins: [
          {
            module: require('postcss-import'),
            options: {
              path: ['node_modules']
            }
          },
          require('tailwindcss')('./app/tailwind/config.js')
        ]
      }
    }
  });
  return app.toTree();
};

Create new CSS files and import Tailwind

Create app/styles/components.css and app/styles/utilities.css then update app.css

@import "tailwindcss/base";

@import "tailwindcss/components";
@import "components.css";

@import "tailwindcss/utilities";
@import "utilities.css";

Now you can start to add Tailwind classes to your project, add additional configuration including custom components and utilities.

Reference for this was taken from https://github.com/chrism/emberjs-tailwind-purgecss

Splitting & Migrating your Ember project to a Monorepo

2020-03-01T00:06:00+00:00

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 is that, in 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 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 package had changed since 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

At 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

2019-04-14T00:06:43+00:00

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?

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?