DEV Community: Rubén Below

How to Contribute to the Gatsby Repository

Rubén Below — Wed, 18 Mar 2020 18:29:09 +0000

Learn how to contribute code to the open source project Gatsby

In Gatsby all projects are packages including Gatsby, plugins, and themes: It's a monorepo managed with Lerna.

At the end of this tutorial, you'll have a working local setup where you can test your changes to a Gatsby package.

Gatsby is one of the favorite static site generators right now. With more than 42.000 GitHub stars it's a major contributor to the Jamstack concept. I would even say, one of their flagships.

The source code lives on Github and everybody is welcome to contribute to the project.

If you encounter some problem while following this tutorial. Take a look at the troubleshooting section, at the end of this post.

Let's start.

Set Up the Gatsby Project

Go to the Gatsby GitHub project and fork it.

The Gatsby project itself, all his packages, and the contributors documentation use Yarn as the package manager (find out how to install Yarn).

Clone the forked repo to your local machine.

# clone the fork
git clone --depth=1 https://github.com/<your-username>/gatsby.git

# go to gatsby
cd gatsby/

# install and build the projects
yarn run bootstrap

# check if everything works
yarn test

Configure the Git upstream.

# check your current remote configuration
git remote -v

# configure the original gatsby repo as your remote upstream
git remote add upstream https://github.com/gatsbyjs/gatsby.git

# check if the configuration has updated
git remote -v

# download objects and refs from the upstream
git fetch upstream

# integrate the upstream master into your local branch
git merge upstream/master

Create a branch.

# create the branch where you're going to work
git checkout -b <feature-or-bugfix>/<feature-or-bugfix-name>

Create a symlink to a Gatsby package.

# change to the package directory (in this case a gatsby plugin)
cd packages/gatsby-transformer-remark/

# create the global symlink to the package
yarn link

# start watching the package files for changes
yarn watch

Add console.warn(`HELLO_GATSBY_DEVELOPMENT`) to gatsby-transformer-remark.

// in packages/gatsby-transformer-remark/src/on-node-create.js:16

// code...

const { createNode, createParentChildLink } = actions;

// Add the next line before the if:
console.warn(`HELLO_GATSBY_DEVELOPMENT`);

// We only care about markdown content.
if (
  node.internal.mediaType !== `text/markdown` &&
  node.internal.mediaType !== `text/x-markdown`
) {
  return {};
}

// more code...

Set Up a Gatsby Site

Now you're going to set up a Gatsby site as an end-user would do. This will help you to test the changes you're doing to the Gatsby project.

Gatsby CLI generated sites and the Gatsby end-user documentation use npm.

Open a new terminal and create a Gatsby test site.

# install gatsby-cli
npm i -g gatsby-cli

# go back to your workspace directory
cd ../../../

# create a new gatsby site
gatsby new gatsby-test-site

# change directory into site folder
cd gatsby-test-site/

Link the Gatsby plugin inside gatsby-test-site.

# link the local package (the package will not appear in your package.json)
npm link gatsby-transformer-remark

Add configuration to gatsby-config.js.

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      // CommonMark mode (default: true)
      commonmark: true,
      // Footnotes mode (default: true)
      footnotes: true,
      // Pedantic mode (default: true)
      pedantic: true,
      // GitHub Flavored Markdown mode (default: true)
      gfm: true,
      // Plugins configs
      plugins: []
    }
  }
];

Start the gatsby-test-site.

gatsby develop

You should see the HELLO_GATSBY_DEVELOPMENT in the terminal.

Congratulations! You have a working Gatsby environment. And you can start contributing to the open source project right now.

Find first-time friendly issues on the Gatsby project issues tab.

You got questions or want to start a conversation? Contact me on Twitter or GitHub!

By the way: don't forget to test and lint the package you're changing.

# from the root of the gatsby repo
yarn jest gatsby-transformer-remark

yarn lint

Happy coding!

Troubleshooting

gatsby develop throws errors

When executing gatsby develop on your gatsby-test-site throws errors:

Clean up the Gatsby cache with gatsby clean. If the problem persists remove node_modules, and package-lock.json and do npm i

To make it easier for the future add a script to your package.json.

{
  "scripts": {
    "clean:npm": "rm -rf ./node_modules/ && rm ./package-lock.json"
  }
}

Error: ENOSPC: System limit for number of file watchers reached

If you get a System limit for number of file watchers reached error, while watching files on a Linux distribution:

Increase the file watch limit of your OS

Kudos for learning with this tutorial.

Follow me on GitHub or Twitter.

If for some casual the indications did not work for you; drop me a line with the infringing points. I'll update the post correspondingly.

Software Versions

These are the software versions used for this tutorial:

Gatsby: 2.19.32
Gatsby CLI: 2.8.27
gatsby-transformer-remark: 2.6.55
Node.js: 12.16.1
npm: 6.13.4

References

Routing an External Registered Apex Domain to an AWS S3 Bucket

Rubén Below — Thu, 12 Mar 2020 19:40:02 +0000

Your website will be accessible with HTTP. To access it with HTTPS do these three extra steps:

Create a certificate with the AWS Certificate Manager for your domain
Create an AWS CloudFront distribution for your "root" S3 bucket. Associate the certificate to it
Point the ALIAS record of your apex domain to the new CloudFront distribution

How to Point a Naked Domain - Not Registered with Route 53 - to an AWS S3 Hosted Static Website

So people can access your website through example.com instead of www.example.com.

In this post, we're going to connect an apex domain with an AWS S3 hosted website. The naked domain is bought in a domain name registrar other than AWS Route 53. In this case OVH. For other registrars the steps are similar.

Apex domains, generally, cannot make use of CNAME records. Allowed are A or AAAA records, pointing to static IPs. This makes it harder to use our naked domain for our website: example.com. This is because of the dynamic nature of AWS S3 instances. They expose a subdomain endpoint, so they can route the internal traffic with freedom.

Let's start.

Copy your current zone file

Log in to your OVH account, go to: Domains > DNS zone, and reduce the TTL (Time to Live). The authoritative name servers cache will expire faster now. This is good because we're going to change the NS (Name Server) records.

Now click on: DNS zone > Change in text format, and copy your RRs (Resource Records).

It should look like:

$TTL 3600
@   IN SOA dns18.ovh.net. tech.ovh.net. (2019112215 86400 3600 3600000 300)
                          IN NS     dns18.ovh.net.
                          IN NS     ns18.ovh.net.
                          IN MX     100 mx3.mail.ovh.net.
                          IN MX     1 mx1.mail.ovh.net.
                          IN MX     5 mx2.mail.ovh.net.
                          IN A      ???
                          IN AAAA   ???
                          IN TXT    "1|www.rubenbelow.com"
                      600 IN TXT    "v=spf1 include:mx.ovh.com ~all"
_autodiscover._tcp        IN SRV    0 0 443 mailconfig.ovh.net.
_imaps._tcp               IN SRV    0 0 993 ssl0.ovh.net.
_submission._tcp          IN SRV    0 0 465 ssl0.ovh.net.
autoconfig                IN CNAME  mailconfig.ovh.net.
autodiscover              IN CNAME  mailconfig.ovh.net.
ftp                       IN CNAME  rubenbelow.com.
imap                      IN CNAME  ssl0.ovh.net.
mail                      IN CNAME  ssl0.ovh.net.
pop3                      IN CNAME  ssl0.ovh.net.
smtp                      IN CNAME  ssl0.ovh.net.
www                       IN CNAME  ???

Some values are replaced with: ???

In the next step, we're going to import our entries in AWS Route 53. Before, let us delete some entries.

Records to delete:

IN NS     dns18.ovh.net.
IN NS     ns18.ovh.net.
...
IN A      ???
IN AAAA   ???
...
www                       IN CNAME  ???

Create an AWS Route 53 Hosted Zone

Log in to your AWS console, go to Route 53, and click on: Create Hosted Zone. As: Domain Name, use the name of your apex domain: example.com.

Modify your DNS file SOA record

Before starting with the next step we need to change the SOA (Start of Authority) record to match the new one.

Change:

@   IN SOA dns18.ovh.net. tech.ovh.net. (2019112215 86400 3600 3600000 300)

To the SOA record in your new Hosted Zone.

The entry should now be like:

@   IN SOA ns-289.awsdns-36.com. awsdns-hostmaster.amazon.com. 1 7200 900 1209600 86400

Import your DNS file into Route 53

Now that we have a fresh hosted zone we'll import the RR records we exported from OVH.

Do not import the previously deleted NS, A, and AAAA records!

Click on your new Hosted Zone: example.com (you'll see a list of RRs)
Click on: Import Zone File
Paste your previously exported DNS records
Import your DNS records

If you get: "Error parsing zone file: One resource cannot have multiple distinct TTL values". Delete the mismatching TTL from the zone file.

From:

600 IN TXT    "v=spf1 include:mx.ovh.com ~all"

To:

IN TXT    "v=spf1 include:mx.ovh.com ~all"

Add an ALIAS record

So far, so good.

Now we add an A ALIAS record for the naked domain; example.com pointing to our AWS S3 bucket.

It should be like this but with an S3 bucket URL instead of a CloudFront URL

Do the same now with an AAAA record.

Add a CNAME record

Add a CNAME record for your www subdomain pointing to your apex domain: example.com.

It should be like this

Get your new NS entries

Get the values of your NS entry. We're going to use them at OVH in the next step.

They should be like:

ns-289.awsdns-36.com.
ns-1715.awsdns-22.co.uk.
ns-1241.awsdns-27.org.
ns-740.awsdns-28.net.

Add your new AWS NS values to your domains registrar

In your OVH account go to: DNS servers

Delete the old OVH NS records
Add your new AWS NS records

Good to go.

Troubleshooting

The changes will take some time to propagate (sometimes up to 24h). We can check the state of the DNS (Domain Name Server) update on:

If the DNS update is done but you cannot access example.com through your computer, it could be that your ISP (Internet Service Provider) still did not update their RR cache. In this case, you should be able to access your website through a VPN.

Thanks for learning with this tutorial.

Follow me on GitHub.

If for some casual the indications did not work for you; don't mind to drop me a line with the infringing points. I'll update the post correspondingly.

References

Welcome

DEV Community: Rubén Below

How to Contribute to the Gatsby Repository

Learn how to contribute code to the open source project Gatsby

Set Up the Gatsby Project

Set Up a Gatsby Site

Troubleshooting

gatsby develop throws errors

Error: ENOSPC: System limit for number of file watchers reached

Software Versions

References

More Posts

Routing an External Registered Apex Domain to an AWS S3 Bucket

How to Point a Naked Domain - Not Registered with Route 53 - to an AWS S3 Hosted Static Website

Copy your current zone file

Create an AWS Route 53 Hosted Zone

Modify your DNS file SOA record

Import your DNS file into Route 53

Add an ALIAS record

Add a CNAME record

Get your new NS entries

Add your new AWS NS values to your domains registrar

Troubleshooting

References

More Posts