Migration Guide from Electric to Gatsby

Migration Guide from Electric to Gatsby

- What is? Maintainability?

What is Electric and Gatsby?

These platforms have been created to build static pages and help developers to create amazing websites using an established Front End architecture.

So, what the status of this platforms?

Gatsby is maintained by a powerful community and it's made by super community-backed tools like React and GraphQL. Actually(November 2018) a lot of websites were built using this tool, check this link for Gatsby's showcase.

Electric was maintained by Liferay using some internal tools like Metal.js and Senna.js to be a sandbox for this tools. However, Liferay had discontinued this project due to internal decisions.

Therefore, Liferay decided to create a simple project to ease the experience to migrate a project from a discontinued project to an existing. Called Gatsby Boilerplate.

- Let's start the migration!

First considerations:

Using Gatsby Boilerplate to migrate you will note that:

Styling:

Electric uses Marble.css as a base for his components, however, this project isn't too accessible to the community and with Liferay Cloud this CSS framework probably will be discontinued to use only Clay.css as base. Clay is a CSS framework developed by Liferay to create the company products and is backed by a great internal and community team that maintains this project. You could use another CSS framework, setting gatsby-plugin-sass to another CSS framework package.

Structure:

Content folder

For changes on content, you could use the content folder located on the root of the generated project. Note that markdown receives some variables(called frontmatter) on top of the file, we will use a lot of them to personalize content, rules of visualization and website integration with services like Auth for example. Note that we have a folder for each template and each template has his particularities.

Note that this page is exactly the same as pages folder on Electric.

Pages folder

We could create static OOTB(out of the box, without a template) pages using this folder. Check this link.

Static folder

Here, we can host our static assets, like images, videos, JSON to our application consume. Note that during build process all folders and files will be served on the root of the output build folder, called public.

GraphQL

Gatsby uses GraphQL to load data into project's React components during Server-Side Rendering, check this link, thereby, you must be familiar with this tool to provide better customizations(like new frontmatter fields, API changes) for your web app.

Markdown Rendering

On Gatsby Boilerplate all content that will be inserted on each page it's inserted using Markdown, the same content template language of Electric. Check this 3 minutes tutorial to be familiar with Markdown if you aren't familiar.

Gatsby Boilerplate uses Gatsby MDX for render Markdown.

Last but not least important

• We don't use layout frontmatter variable as a variable to define what template can be used because Gatsby Boilerplate resolves it for us using the folder name. This variable is called internally templateKey if you want to check how it's implemented.

• Note that, like Electric, our page URL is the same as the name of the correspondent Markdown file.

Start migrating content from Blog Template:

We could migrate all our content to blog using the content folder as mentioned before.

Note that Electric has the same possible values to be passed to the frontmatter of a post.

Electric blog frontmatter example:

---
title: "Markdown Post"
description: "Lorem ipsum dolor sit amet, consectetur adipisicing elit."
date: "February 02, 2017"
author: "Author Name"
layout: "blog"
---

Gatsby blog frontmatter example:

---
author: Diego Nascimento
banner: /images/flavor_wheel.jpg
date: 2016-12-17T15:04:10.000Z
description: The Coffee Taster’s Flavor Wheel, the official resource used by coffee tasters, has been revised for the first time this year.
title: Making sense of the SCAA’s new Flavor Wheel
---

Changes:

frontmatter:

• date follow a date standard to Gatsby analyze and decode date. You can change time format on date query field on blog template file to another format, for example, from "MMMM DD, YYYY" to "DD MMMM, YYYY"
• banner is an optional frontmatter that can be used to expose a banner for the post on blog list of our blog.

Note that we don't need to pass our values between quotation marks

Considering this, we can proceed just copying and paste our content from a markdown file into blog content folder.

Start migrating content from Docs Template:

special thanks for Matuzalém Teles who developed a part of this template on clayui.com

We have 2 possible use cases for Docs navigation:

• We could create a section that is used as a page too.
• We could create a tree of sections that can be used to nest sections and pages.

Changes:

frontmatter:

• redirect is an optional frontmatter that can be used to redirect a route or page to another. When you are trying to access a page route, this page will redirect you for another that had been described on redirect frontmatter.

Search Component:

• Seach Component was removed because isn't working in an adequated way. Algolia search was inserted to provide this search service. To enable Algolia search on your template you can set ALGOLIA_API_KEY and ALGOLIA_INDEX_NAME environments variables on .env files.

More info you could view .env files section

We could use Code Tabs with an option to copy our code using the default markdown code notation. For example:

	```javascript
	function dale() {
	    console.log('oiw');
	}
	```

Start migrating content from Updates Template:

We could use the same Markdown frontmatter to make changes on the Updates template.

Start migrating content from Tutorials Template

Note that Tutorials template was renamed to Onboarding due usage on Onboarding pages, If you didn't agree that, fill an issue.

Changes:

frontmatter:

• stepNumber frontmatter variable is a number that you can provide to order your markdown files in steps.
• time frontmatter was removed because this time to read is calculated internally, however, the time to read component wasn't completed yet.
• buttonTitle was removed because is unused in most of the projects.

- Additional features

Auth

If you want to restrict a page, you can use needsAuth frontmatter on the top of any markdown file. When you set to true, this page will be restricted for private users only.

This authentication is provided by a WeDeploy Auth service that can be set on a .env.production or .env.development file. These files configuration will be explained in the next section.

Progressive Web App support

Gatsby Boilerplate is a Progressive Web App, if you aren't familiar with this term, check this link.

During the development, this boilerplate was battle tested to turns it into a real PWA covering all PWA checklist.

We could personalize our progressive web app manifest file changing the values on Gatsby-config.js file.

PS: this files will be created only in build time when you perform a gatsby build.

Offline Support

We could personalize what type of files we can cache on Gatsby-config.js file on gatsby-plugin-offline options. Default extensions are: js,jpg,png,gif,html,css,svg

GZIP compression

If you want to disable the default zopfli plugin to compress our files just remove gatsby-plugin-zopfli on Gatsby-config.js.

Config and enviroment(.env) files

Gatsby uses a standard to define enviroment variables on his code.

You can provide environment variables to your site to customize its behavior in different environments. Gatsby Boilerplate offers two possible files: .env.production which is used to set environment variables on production and .env.development that can be used to set environment variables on development.