DEV Community: Robin Philip Thomas

Level up your React component architecture

Robin Philip Thomas — Sun, 31 Jul 2022 19:13:15 +0000

With newer versions of React focusing more on functional components, hooks and context, it is time that we re-look some of the component patterns in react.

Components are the heart of React, so understanding how to utilize them is paramount to creating an effective design structure. In this article, we will be looking at some popular design patterns for building React components.

1. Render props pattern

This is one of the simplest component patterns. Here you pass components as props to your parent component and the parent component takes care of rendering it in the right place.

A render prop is a prop on a component, whos value is a function that returns a JSX element. The component simply calls the render prop at the right place within the template.

Let's look at a sample Modal component. We want your Modal component to display a custom Title and Footer based on the page they are called. The render props pattern is what we will use here.

Usage

<Modal title={<CustomModalTitle />} footer={<CustomModalFooter />}>

CustomModalTitle and CustomModalFooter are components specific to the page that the user passed to the Modal component. Modal component accepts them as props and renders them appropriately.

Implementation

export const Modal = ({ title, footer, children }) => {
  return (
    <div className="modal">
      <div className="modal-title">{title}</div>
      <div className="modal-content">{children}</div>
      <div className="modal-footer">{footer}</div>
    </div>
  );
};

Lifting state up

Through the render prop pattern, we can also pass internal data from the parent Modal component to the incoming render prop elements.

export const Modal = ({ title, footer, children }) => {
 const data = { ... }

  return (
    <div className="modal">
      <div className="modal-title">{title}</div>
      <div className="modal-content">{children}</div>
      <div className="modal-footer">{footer(data)}</div>
    </div>
  );
};

The render prop can now receive this value like this:

<Modal
        ...
  footer={(data) => <CustomModalFooter data={data} />}
>

Children as a render prop

Besides regular JSX components, we can pass functions as children to React components. This function is available to us through the children prop, which is technically also a render prop.

Let's update our example so that we also pass our internal data value to children as well.

export const Modal = ({ title, footer, children }) => {
 const data = { ... }

  return (
    <div className="modal">
      <div className="modal-title">{title}</div>
      <div className="modal-content">{children(data)}</div>
      <div className="modal-footer">{footer(data)}</div>
    </div>
  );
};

Calling the Modal component can be changed to this:

<Modal ... >
  {(data) =>(
      <div>
        Hello, {data.name}
      </div>
    )
  }
</Modal>

Here's this component in action:

https://codesandbox.io/embed/render-props-pattern-rjfti1?fontsize=12&hidenavigation=1&theme=dark

Pros

Simple to implement and understand.
Sharing logic and data among several components is easy with the render props pattern. Components can be made very reusable, by using a render or children prop.

Cons

No control over what users pass as render prop.
Quite difficult to achieve tight logic sharing between render prop elements and parent component.

2. Compound component pattern

The compound components are a set of two or more components that work together to accomplish a specific task. The set of components will share an implicit state to communicate between them.

Think of compound components like the <select> and <option> elements in HTML. Apart they dont do too much, but together they allow you to create a complete experience.Kent C. Dodds

<select>
 <option>Option1</option>
 <option>Option2</option>
 <option>Option3</option>
 <option>Option4</option>
</select>

Alright, let's take a look at a legit React component that exposes a compound component to understand these principles further. Here's an example of the <CheckboxGroup /> component that exposes a compound components API:

 <CheckboxGroup
  title="hello form"
  checkedItems={checkedItems}
  onChange={onCheckBoxChange}
>
    <CheckboxGroup.Item label="One" name="one" />
    <CheckboxGroup.Item label="Two" name="two" />
</CheckboxGroup>

In this example, the <CheckboxGroup> establishes some shared implicit state. The <CheckboxGroup.Item> components each access and/or manipulate that state, and it's all done implicitly. This allows you to have the expressive API you're looking for.

checkedItems and onChange are passed to the CheckboxGroup and they are then internally passed to all the innerCheckboxGroup.Items.

Let's look at the implementation

export const CheckboxGroup = ({
  title,
  checkedItems,
  onChange,
  children
}) => {
  const providerState = useMemo(
    () => ({
      checkedItems,
      onChange: onChange
    }),
    [checkedItems, onChange]
  );

  return (
    <div >
      <form>
        {
          // So here we can take all children and make a copy of them that has those props.
          Children.toArray(children).map((child) => {
            if (isValidElement(child)) {
              return cloneElement(child, {
                ...child.props,
                ...providerState
              });
            }
            return null;
          })
        }
      </form>
    </div>
  );
};

export const CheckboxItem = ({
  name,
  label,
  checkedItems,
  onChange
}) => {
  return (
    <label className="container">
      {label}
      <input
        type="checkbox"
        name={name}
        checked={checkedItems!.includes(name)}
        onChange={onChange}
      />
      <span className="checkmark"></span>
    </label>
  );
};

CheckboxGroup.Item = CheckboxItem;

When creating reusable components, we want to provide a component where the consumer has control over where or how many elements are rendered in their code.

The <CheckboxItem components will need access to the internal state, the internal onChange function, as well the user's props, for the experience to work properly. But how do we pass this data to the sub-components? This is where React.Children.toArray and React.cloneElement comes into play.

CheckboxGroup - Parent component to which we pass our state and onChange events.
React.Children.toArray(children).map - It iterates through the component's direct children, allowing us to manipulate each direct child.
React.cloneElement - Clone and return a new React element with some extra props.

With React.Children.toArray(children).map and React.cloneElement we are able to iterate and manipulate each child. So we are able to pass additional props that we explicitly define in this transformation process. In this case, we can pass the CheckboxGroup internal state to each CheckboxItem child component. Since React.cloneElement performs a shallow merge, any props defined by the user on CheckboxItem will be passed to the component.

Finally, we can declare the CheckboxItem static property component on our CheckboxGroup component. This allows the consumer to call our subset component, CheckboxItem, directly from CheckboxGroup using the dot-syntax notation. This helps improve readability and explicitly declares the sub-components.

Here's this component in action:

https://codesandbox.io/embed/compound-component-pattern-0hz6qw?autoresize=1&fontsize=12&hidenavigation=1&theme=dark

Pros

Expressive component API
Implicit props sharing between parent and child components
Users have more control over the templating.

Cons

Does not work when there are multiple nested elements. (Since we only close the direct children)
Can break if the user decides to add other elements to children.

3. Context compound component pattern

Context compound is a more flexible version of the compound component pattern we saw before. The problem with compound components is that they can only clone and pass props to immediate children.

With Context compound component, we can implicitly access the internal state of our component regardless of where they're rendered within the component tree. Another reason to use Context compound components is when several components need to share states, regardless of their position in the component tree.

The consumer of the component should be free to choose where to render our compound components. In order to accomplish this, we will use React's Context API.

How is this more flexible you ask? Let's look at an example. We'll build a counter component with + and - buttons to increment/decrement the count.

The component API would look as such

<Counter onChange={handleChangeCounter}>
  <Counter.Decrement />
  <Counter.Label>Counter</Counter.Label>
  <Counter.Count />
  <Counter.Increment />
</Counter>

Flexible Markup Structure: Your component has great UI flexibility, allowing the creation of various cases from a single component. For example, the user can change the SubComponents order or define which one should be displayed.

Let's look at the implementation

import { Decrement, Increment, Label, Count } from "./components";

export const Counter = ({
  children,
  onChange,
  initialValue = 0
}) => {
  const [count, setCount] = useState(initialValue);

  const handleIncrement = useCallback(() => {
    setCount(count + 1);
    onChange(count + 1);
  }, [count, onChange]);

  const handleDecrement = useCallback(() => {
    setCount(Math.max(0, count - 1));
    onChange(Math.max(0, count - 1));
  }, [count, onChange]);

  const value = useMemo(() => {
    return {
      count,
      handleIncrement,
      handleDecrement
    };
  }, [count, handleIncrement, handleDecrement]);

  return (
    <CounterProvider value={value}>
      <div className="counter-wrapper">{children}</div>
    </CounterProvider>
  );
};

Counter.Decrement = Decrement;
Counter.Increment = Increment;
Counter.Label = Label;
Counter.Count = Count;

We start by creating a context and wrapping the whole component inside a ContextProvider. We pass our shared state and function to the context so that all child components have access to it.

<CounterProvider value={value}>
  <div className="counter-wrapper">{children}</div>
</CounterProvider>

Getting the state in the sub-components is as simple as reading from the context.

export const Count = () => {
  const { count } = useContext(CounterContext);;

  return <div className="counter-count">{count}</div>;
};

Here's this component in action:

https://codesandbox.io/embed/context-component-pattern-58xr2r?autoresize=1&fontsize=14&hidenavigation=1&theme=dark

Pros

Reduced API Complexity: Instead of jamming all props in one giant parent component and drilling those down to child UI components, here each prop is attached to the SubComponent that makes the most sense.
Flexible Markup Structure: Your component has great UI flexibility, allowing the creation of various cases from a single component. For example, the user can change the SubComponents order or define which one should be displayed.
Separation of Concerns: Most of the logic is contained in the main Counter component, a React.Context is then used to share states and handlers across all children. We get a clear division of responsibility.

Cons

Too much UI flexibility: Having flexibility comes along with the possibility to provoke unexpected behaviour (putting an unwanted Components child, making out of order the Components children, forgetting to include a mandatory child).

4. Custom hook pattern

In this pattern, we use a custom hook along with the component template. All the logic needed for the component to work comes from this custom hook. This makes it possible for you to share logic without being opinionated about the UI.

Let's look at an example where we build a sample toggle component.

export default function App() {
  const { on, toggle, setOn, setOff } = useToggle();

  return (
    <div>

        <button onClick={setOn}>turn on</button>
        <button onClick={setOff}>turn on</button>

      <Toggle on={on} onClick={toggle} />
    </div>
  );
}

From the useToggle hook we get the handlers and state for the toggle switch.useToggle hook can even be modified to pass props to it, to be used in the logic.

eg:

const { on, toggle, setOn, setOff } = useToggle({ initialValue: true });

Let's look at the implementation

export const useToggle = () => {
  const [on, setOnState] = useState(false);

  const toggle = () => setOnState((o) => !o);
  const setOn = () => setOnState(true);
  const setOff = () => setOnState(false);

  return { on, toggle, setOn, setOff };
};

Here's this component in action:

https://codesandbox.io/embed/modern-snowflake-30uj3r?autoresize=1&fontsize=14&hidenavigation=1&theme=dark

Pros

Give more control: The user can insert their own logic between the hook and the JSX element, allowing them to modify the default component behaviour.

Cons

Implementation complexity: Since the logic part is separated from the rendering part, it is the user who must link both. A good understanding of how your component works is required to correctly implement it.

5. State reducer pattern

This pattern is similar to the Custom hook pattern, but in addition, the user defines a reducer which is passed to the hook. This reducer will overload any internal action of your component.

Now, let's say we wanted to adjust the <Toggle /> component so the user couldn't click the Switch more than 4 times in a row unless they click a "Reset" button.

As a user, it'd be cool if I could hook into every state update before it actually happens and modify it. We can achieve this by passing a reducer to the hook. The reducer will have currentState and action as params. Then the action could have a type that determines what type of change is happening, and we could get the changes from the toggleReducer which would be exported by our useToggle hook. We'll just say that the type for clicking the switch is TOGGLE.

usage

export default function App() {
  const [clicksSinceReset, setClicksSinceReset] = useState(0);
  const tooManyClicks = clicksSinceReset >= 4;

  const { on, toggle, setOn, setOff } = useToggle({
    reducer(currentState, action) {
      const changes = toggleReducer(currentState, action);
      if (tooManyClicks && action.type === ActionTypes.toggle) {
        // other changes are fine, but on needs to be unchanged
        return { ...changes, on: currentState.on };
      } else {
        // the changes are fine
        return changes;
      }
    }
  });

  return (
      <div>
          <button onClick={setOff}>Switch Off</button>
          <button onClick={setOn}>Switch On</button>

        <Toggle
          onClick={() => {
            toggle();
            setClicksSinceReset((count) => count + 1);
          }}
          on={on}
        />
        {tooManyClicks ? (
          <button onClick={() => setClicksSinceReset(0)}>Reset</button>
        ) : null}
      </div>

Let's take a look at how we could implement this with our useToggle hook.

We could add logic to every one of these helper functions. However, I'm just going to skip ahead and tell you that this would be really annoying, even in this simple hook. Instead, we're going to rewrite this from useState to useReducer and that'll make our implementation a LOT easier:

const toggleReducer = (state: ToggleState, action: ToggleAction) => {
  switch (action.type) {
    case ActionTypes.toggle: {
      return { on: !state.on };
    }
    case ActionTypes.on: {
      return { on: true };
    }
    case ActionTypes.off: {
      return { on: false };
    }
    default: {
      throw new Error(`Unhandled type: ${action.type}`);
    }
  }
};

export const useToggle = () => {
  const [{ on }, dispatch] = useReducer(toggleReducer, { on: false });

  const toggle = () => dispatch({ type: ActionTypes.toggle });
  const setOn = () => dispatch({ type: ActionTypes.on });
  const setOff = () => dispatch({ type: ActionTypes.off });

  return { on, toggle, setOn, setOff };
};

Every handler fires a dispatch call to the reducer with the relevant ActionType.

We also want users to pass a custom reducer if they need to as a configuration object to our useToggle function, so let's accept that:

export const useToggle = ({ reducer = toggleReducer } = {}) => {
  const [{ on }, dispatch] = useReducer(reducer, { on: false });

  const toggle = () => dispatch({ type: ActionTypes.toggle });
  const setOn = () => dispatch({ type: ActionTypes.on });
  const setOff = () => dispatch({ type: ActionTypes.off });

  return { on, toggle, setOn, setOff };
};

See how we give a default value to the reducer in useToggle. The default value will be used if the user does not want to modify the default behaviour.

Okay, so now that we have the developer's reducer, how do we combine that with our reducer? Well, if we're truly going to invert control for the user of our hook, we don't want to call our own reducer. Instead, let's expose our own reducer and they can use it themselves if they want to, so let's export it, and then we'll use the reducer they give us instead of our own:

export const toggleReducer = (state: ToggleState, action: ToggleAction) => ...

Awesome, so now people can use our useToggle hook with their own reducer or they can use it with the built-in one. Either way works just as well.

Here's this component in action:

https://codesandbox.io/embed/state-reducer-pattern-vz9lyt?autoresize=1&fontsize=14&hidenavigation=1&theme=dark

Pros

Give more control: In the most complicated cases, using state reducers is the best way to leave control to the user. All your internal components actions are now accessible from the outside and can be overridden.

Cons:

Implementation complexity: This pattern is surely the most complex to implement, both for you and for the user.
Lack of visibility: Since any reducers action can be changed, a good understanding of the Components internal logic is required.

6. Props getter pattern

Custom hook pattern gives great control, but also makes your component harder to integrate. This is because the user has to deal with a lot of native hook props and recreate the logic on his/her side. The Props getters pattern attempts to mask this complexity. Instead of exposing native props, we provide a shortlist of props getters. A getter is a function that returns many props, it has a meaningful name allowing the user to naturally link it to the right JSX element.

Let's see how our Toggle example would look if we were using props getter pattern.

export default function App() {
  const { on, getTogglerProps } = useToggle();

  return (
    <div>

      Toggle state: {on ? "on" : "off"}
      <Toggle {...getTogglerProps()} />
    </div>
  );
}

getTogglerProps() takes care of passing the right props to the <Toggle/> component.

Implementation would look something like this:

const callAll = (...fns: Function[]) => (...args: any) =>
  fns.forEach((fn) => fn && fn(...args));

export const useToggle = () => {
  const [on, setOnState] = useState(false);

  const toggle = () => setOnState((o) => !o);

  const getTogglerProps = (props: any = {}) => ({
    on: on,
    "aria-expanded": on,
    tabIndex: 0,
    ...props,
    onClick: callAll(props?.onClick, toggle)
  });

  return { on, toggle, getTogglerProps };
};

getTogglerProps function makes sure that our Toggle component receives the toggle state, onClick action and also has the correct aria-label and tabIndex values.

If we want to override the default behaviour, all we have to do is explicitly pass the props to override to the <Toggle /> component.

<Toggle {...getTogglerProps()} tabIndex={-1}/>

Here's this component in action:

https://codesandbox.io/embed/props-getter-pattern-b75zm7?autoresize=1&fontsize=14&hidenavigation=1&theme=dark

Pros

Ease of use: Provide an easy way to integrate your component, the complexity is hidden, and the user just has to connect the correct getter to the right JSX element.
Flexibility: The user is able to overload the props within the getters to adapt to their specific needs.

Cons

Lack of visibility: The abstraction brought by the getters makes your component easier to integrate, but also more opaque and magic. To correctly override your component, the user has to know the list of props exposed by the getters and the internal logic impact if one of them is changed.

Conclusion

We looked at some of the core functional component patterns in React(that I know of). But in a real-world situation, you could build components that use multiple of these patterns together to make an extremely flexible API for situations where that's useful.

It is your role as a developer to choose the correct pattern corresponding to the right need. Whether to give the users of the component more control over the internal workings of the component or not.

This article was mainly inspired by the amazing work of Kent C. Dodds and Alexis Regnaud. Take a look at their blogs (Kent, Alex) if you are interested in knowing more about each of the patterns.

I hope you have found this useful. If you decide to try some of these patterns or need any help, send me a message on Twitter. I would love to help.

Let's do some CSS Wrap!

Robin Philip Thomas — Mon, 03 May 2021 04:36:54 +0000

Nope, I'm not writing a rap song on CSS 🎤.
But something better 😁.

A cheat sheet on various ways of text wrapping and overflow handling in CSS.

🖐
I know what you're thinking! "I know how to handle text wrapping and overflow in CSS. I've been doing them since forever." But believe me, there are some new properties and some major depreciations ongoing. Wouldn't hurt to spend 3min reading.

So without further adieu.

Text overflow handling in CSS is done using mostly these properties.

Quite a handful of options right! Wondering all properties and values to use?

Lucky for you, here's a list of the most common text-overflow handling scenarios and their CSS code snippets. 🎁

If you would like to read about text-overflow in general and what many of the above properties do, I highly recommend you read this MDN blogpost.

case 1

  overflow-wrap: break-word;

This property will move the last word in the line to the next line if it is too long to fit on the same line by itself without overflowing.

Downsides:
👎 But the downside is, you might get some empty spaces if the next word does not fit in the line.

Upsides:
👍 Good enough when container size is not small (>500px).
👍 Good browser support.

case 2

  text-align: justify;
  overflow-wrap: break-word;

Let's say you like case-1 but don't want those empty spaces at the line end. One solution is to justify the line text so that the end spaces are distributed throughout the line.

Downsides:
👎 Spaces between words might look uneven. Much evident when container size is small (<300px).
👎 justify only works if there are at least two words in the line.

Upsides:
👍 Good enough when container size is medium or larger (>300px).
👍 Good browser support.

case 3

  text-align: justify;
  word-break: break-all;

If you have a small container and want the whole line to be filled with letters and at the end of the line break on any word/letter. Then use this.

Downsides:
👎 if used on large container widths, can make reading the line's harder as the last words as split up in between.

Upsides:
👍 Best for small container widths.
👍 The whole container looks filled from side to side per line. (some designs might need that.)
👍 Good browser support.

case 4

  hyphens: auto;

if you wanna a mix of overflow-wrap: break-word; and word-break: break-all;, I would say use this. With hyphens:auto, the browser is free to automatically break words at appropriate hyphenation points, following whatever rules it chooses.

Downsides:
👎 Word/letter breaking not predictable.
👎 Needs vendor prfixes to work with all browsers

Upsides:
👍 Adds a hyphen(-) when breaking words in between. Makes readability slightly better.
👍 hyphens is language sensitive based on lang attribute.

Before we go to the next case, two bonus tips .

word-break: break-word;(just the break-word value) has been deprecated. Use overflow-wrap: break-word; instead.
word-wrap: has also been deprecated as a property. Use overflow-wrap instead.

case 5

  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;

Use this when you don't wanna show the overflowing text. 3 dots(...) is shown to convey that there is text being overflown and being hidden.

case 5

Multiline ellipsis

  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow:hidden;

Downsides:
👎 Not so good browser support
👎 You can't have padding on the text container as it will expose extra lines. 🤷‍♂️

That's it. Those were the most common text wrapping and overflow handling cases I could think of.

If you liked what you read, and wanna see what I'm lately up to, follow me on Twitter.

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?