I finally decided to handle this issue with 1password-cli, a command-line utility that can interact with 1Password.

For the sake of this article, I’ll skip the 1password-cli setup and I’m assuming the command op is available on your terminal.

$ which op
/Users/fnando/local/bin/op

The first step is signing in by running the command op signin. Once you’re done you can list your vaults by running the command op vault ls.

$ op vault ls
ID                            NAME
zyxlrxyu53kax7qqrxz554fgbq    Private
oblww37jzanxpl4wruzjz43i71    dev

In my case, I’ll use the vault dev to store my development credentials. You can either create a new item by using the command-line or 1Password’s UI. I’m using a server type:

$ op item create --title main --category server --vault dev
ID:          kbfa7n6hcziy6ck7ys63pzta3a
Title:       main
Vault:       dev (oulww37jzinxpl4wruzjz43i44)
Created:     now
Updated:     now
Favorite:    false
Version:     0
Category:    SERVER
Fields:
  Admin Console:

  Hosting Provider:

I recommend opening 1Password and removing the default sections; unfortunately, I couldn’t find a way of removing sections by using the command-line. You can also remove the default fields, as we won’t use it (password, username and url).

Now you can add secrets to that item by using the command op item edit. Let’s add two secrets by using the command-line. Or you can do the same using 1Password’s user interface.

$ op item edit --vault dev main 'dev.SOME_API_KEY[password]=SOME_KEY' 'dev.ANOTHER_API_KEY[password]=SOME_OTHER_KEY'
ID:          kbfa7n6hcziy6ck7ys63pzta3a
Title:       main
Vault:       dev (oulww37jzinxpl4wruzjz43i44)
Created:     40 seconds ago
Updated:     now by Nando Vieira
Favorite:    false
Version:     2
Category:    SERVER
Fields:
  dev:
    SOME_API_KEY:       SOME_KEY
    ANOTHER_API_KEY:    SOME_OTHER_KEY

The secrets above will be added to a section called dev. Here’s a screenshot showing the secrets in 1Password’s app.

Once you’ve added all secrets to 1Password, it’s time to retrieve the secrets. You can do it so by running the command op item get.

$ op item get --vault dev main --format json
{
  "id": "kbfa7n6hcziy6ck7ys63pzta3a",
  "title": "main",
  "version": 3,
  "vault": {
    "id": "oulww37jzinxpl4wruzjz43i44",
    "name": "dev"
  },
  "category": "SERVER",
  "last_edited_by": "XCFD5SQIJNCZZOF2PBC7XED6QE",
  "created_at": "2022-12-28T08:44:55Z",
  "updated_at": "2022-12-28T00:45:35.033579-08:00",
  "sections": [
    {
      "id": "Section_6r6xfx7vkbniby2fogqg7tvmee",
      "label": "dev"
    }
  ],
  "fields": [
    {
      "id": "notesPlain",
      "type": "STRING",
      "purpose": "NOTES",
      "label": "notesPlain",
      "reference": "op://dev/main/notesPlain"
    },
    {
      "id": "xzuhdgcumcnz5peyvjckq2z4gi",
      "section": {
        "id": "Section_6r6xfx7vkbniby2fogqg7tvmee",
        "label": "dev"
      },
      "type": "CONCEALED",
      "label": "SOME_API_KEY",
      "value": "SOME_KEY",
      "reference": "op://dev/main/dev/SOME_API_KEY"
    },
    {
      "id": "4mg4ejw7q3pnsyworyiflofemq",
      "section": {
        "id": "Section_6r6xfx7vkbniby2fogqg7tvmee",
        "label": "dev"
      },
      "type": "CONCEALED",
      "label": "ANOTHER_API_KEY",
      "value": "SOME_OTHER_KEY",
      "reference": "op://dev/main/dev/ANOTHER_API_KEY"
    }
  ]
}

Notice that 1Password will always return the field notesPlain, as it’s built-in and can’t even be removed.

The next step is using this list and convert it into a format that your terminal will understand. I’m going to use jq for this task.

$ op item get main --vault dev --format json | jq -r '.fields | map(select(has("value"))) | map("export " + .label + "=\"" + .value + "\"") | join("\n")'
export SOME_API_KEY="SOME_KEY"
export ANOTHER_API_KEY="SOME_OTHER_KEY"

You can either use eval with the above output, or output to a file that your terminal will load. I’m going with the second option, but first let’s clean up the house and create an executable script. I’m going to call it op-env.

#!/usr/bin/env bash

set -e

op item get main --vault dev --format json | jq -r '.fields | map(select(has("value"))) | map("export " + .label + "=\"" + .value + "\"") | join("\n")'

Make it executable by running chmod +x op-env. You should see the exports being printed to the screen if you run op-env.

$ op-env
export SOME_API_KEY="SOME_KEY"
export ANOTHER_API_KEY="SOME_OTHER_KEY"

Now you can add the following lines to your profile. If you’re using ZSH, ~/.zshrc will do trick. On Bash you can use ~/.bashrc:

if [ ! -f ~/.op-env ]; then
  op run -- true
  op-env > ~/.op-env
  chmod 600 ~/.op-env
fi

source ~/.op-env

The code above will create the file ~/.op-env unless one already exists, which means your secrets will be cached until this file is removed or you refresh it by running op-env > ~/.op-env. This is required because 1Password will request authorization every first call to op in a terminal session; that is, if you open a new tab, you’ll need to re-authorize op. By caching the results, you only need to do this every once in a while.

Wrapping up

That’s it! Using the 1password-cli allowed me to drop hardcoded secrets, making the secrets sharing way easier.

If you’re using 1password-cli, make sure you also take a look at the .env file support, which is also a neat way of sharing secrets between team members.

How do you handle this problem? Do you use something else? Share your favorite solution in the comments below.

If you’re watching the crypto space, you probably know about Stellar. Stellar is an open network for storing and moving money. You can easily create, send and trade digital representations of all forms of money by using a feature called assets.

Assets are, essentially, custom tokens. Any person can create an asset in just a few steps, and in this article we’ll create one called ACME. Let’s get this started!

Understanding assets

Assets are identified by a code and a Stellar account public key. This identifier is what you use to look up or interact with it on the Stellar network. An asset identifier must be unique (i.e. both code and public key must be unique); you can have multiple assets representing US dollars or Bitcoins using the same code (USD and BTC), but not the same code plus public key.

Let’s say both Binance and Coinbase want to issue Bitcoin assets on the Stellar network; Binance’s asset could be something like BTC:GAAA...BINANCE, and Coinbase’s asset could be BTC:GAAA...COINBASE.

Ultimately, is up to the user to decide which representation is more trustworthy, but a product/service can also make a decision for users based on partnerships; Vibrant uses Stablex’s ARST for Argentine Pesos and Circle’s USDC for US Dollar.

An asset is often used to represent something outside Stellar’s network like fiat currency, bonds, gold, etc, but it can be used to represent pretty much anything, like other crypto currencies, reward points or karma (like in Reddit).

Creating your custom asset

The process of creating a custom asset is fairly simple.

1. You need two accounts; one to issue the asset, one to distribute the asset.
2. To receive the asset, accounts must add a trustline, which is a way of saying “I want to receive/hold this asset”. So, your distribution account must have this trustline established as well.
3. The issuer account sends a payment with the info that defines the asset to the distribution account.
4. The distribution account distributes the asset to any account that have a trustline.
5. That’s it!

As you can see, the process is fairly straightforward. One thing most people don’t understand is that, in practice, there’s no “create asset” step. Basically, anyone can send custom assets to anyone as long as the receiving account have a trustline established.

Technically speaking, we don’t really need to have two separate accounts (issuer and distribution), but that’s a good rule to live by. Sometimes, it’s also a requirement; maybe you want to issue a limited number of assets and, in this case, you’ll need to set the issuer’s signature weight to zero, locking the account and preventing any additional issuance.

The easiest way of issuing a new asset is by using Stellar’s Laboratory. For the purpose of this article, we’ll create the asset on the Testnet, so you don’t need to have any Stellar Lumens (XLM). To create an asset on the public network, the process is virtually the same; just grab some Stellar Lumens (XLM) required to create the accounts and establish the trustlines.

Setting up accounts

First, let’s create the issuer account (i.e. the account that “owns” the asset). Visit https://laboratory.stellar.org and make sure you have the Testnet selected. Under “Create Account”, hit the “Generate keypair” button to create a new Stellar account. It’s your responsibility to keep your private key safe, so use something like a password manager.

Copy the public key and paste it under the Friendbot section, then hit the “Get test network lumens” button. This step will effectively create your account on the Stellar network.

If you visit https://horizon-testnet.stellar.org/accounts/GAGGA4J6MH6JUBUVAUELGVNR7HNH3BWSN7GJHYJUFZPS655TNOCXDIST, you can see that the account now exists on the network. Alternatively, you can use the “Explore Endpoints” tab of the Laboratory.

Notice that the testnet is reset from time to time, so you may receive a page not found back if you visit any of the urls mentioned in this article.

Repeat the same process, now for your distribution account.

Again, you can check that the account exists on the network by visiting https://horizon-testnet.stellar.org/accounts/GBNXJNCPQQZPWRRSMUEXGNTIOZU7FBDVT62WHA6WM6VOFW3YE56ISSUE.

Now that both accounts have been created, we need to make sure the distribution account is ready to receive ACME:GBNXJNCPQQZPWRRSMUEXGNTIOZU7FBDVT62WHA6WM6VOFW3YE56ISSUE. This is done by establishing a trustline.

Understanding Trustlines

Trustline is simply a mechanism to say that an account can receive an asset. By default, all Stellar accounts can only receive Stellar Lumens (XLM), the native asset. Any other asset will require a trustline. Given that trustlines are opt-in, Stellar accounts won’t be filled with spam transactions for assets that won’t ever be used.

Each trustline increases the required account balance by one base reserve, currently set to 0.5 XLM. This means that any account will need two base reserves (required to create the account on the network) plus 0.5 XLM for each trustline. There are other things that may increase the minimum balance required for an account, so make sure you read the Minimum Balance documentation.

Establishing trustlines

To receive the asset ACME:GBNXJNCPQQZPWRRSMUEXGNTIOZU7FBDVT62WHA6WM6VOFW3YE56ISSUE, users will need a trustline. Go to Laboratory’s Build Transaction and paste the account’s public key. In this case, we’re going to set up the distribution account GAGGA4J6MH6JUBUVAUELGVNR7HNH3BWSN7GJHYJUFZPS655TNOCXDIST.

• Paste the public key under “Source Account”, then click “Fetch next sequence number for account starting with…”.
• Add a “Change Trust” operation to establish the trustline. Select “Alphanumeric 4” and use ACME as the asset code and GBNXJNCPQQZPWRRSMUEXGNTIOZU7FBDVT62WHA6WM6VOFW3YE56ISSUE as the issuer account id. If you don’t set a limit, then the maximum limit will be used instead.
• When you’re done, click “Sign in Transaction Signer”.

You’ll be redirected to the Transaction Signer. Paste your private key (the one that starts with a S) and click “Submit in Transaction Submitter”.

Now, you’ll be able to review the transaction. To submit it, click “Submit Transaction”.

The distribution account is all set up to receive ACME:GBNXJNCPQQZPWRRSMUEXGNTIOZU7FBDVT62WHA6WM6VOFW3YE56ISSUE. Now, all we need to do is sending some ACMEs from the issuer account to the distribution account.

Go to the tab “Build Transaction” and paste the issuer account’s public key (GBNXJNCPQQZPWRRSMUEXGNTIOZU7FBDVT62WHA6WM6VOFW3YE56ISSUE), then click “Fetch next sequence number for account starting with…”. Click “Sign in Transaction Signer”.

Paste the issuer’s private key, then click “Submit in Transaction Submitter”.

Finally, submit the transaction.

That’s it! If you visit https://horizon-testnet.stellar.org/accounts/GAGGA4J6MH6JUBUVAUELGVNR7HNH3BWSN7GJHYJUFZPS655TNOCXDIST you can see that the account now have an entry under “balances” with 1,000,000 ACME.

Anyone willing to receive this asset would have to go through this process and establish a trustline. Some wallets like LOBSTR abstracts this process, making it very user friendly.

Exercise: Create another account, and send some tokens from the distribution account to it. Remember, the account needs to establish a trustline to ACME:GBNXJNCPQQZPWRRSMUEXGNTIOZU7FBDVT62WHA6WM6VOFW3YE56ISSUE.

Wrapping up

As you can see, creating new assets on the Stellar network is a very simple process. Obviously, there are other aspects you need to consider, like how users will redeem their assets in the real world, but that’s more of an operational process, and even more important than issuing the assets on the Stellar network.

Stellar is one of the most developer-friendly blockchains out there. It’s fast, and very cheap, especially when compared to networks like Ethereum or Bitcoin.

Make sure you check out the official documentation, where you can find more info about the Stellar network and its features.

I frequently see people struggling to set up HTTPS in development. If you’re a long time developer, you may have done this in the past with self-signed certificates, buying your own certificates and tweaking your hosts file, or using tools like puma-dev. While these approaches work to an extent, Let’s Encrypt changed the game, at least for me.

With Let’s Encrypt and a DNS provider like AWS Route 53, you’ll be able to run HTTPS with wildcard subdomains without having to mess with your /etc/hosts file, or having to install tools that create a custom DNS resolver.

I’m going to focus on macOS, my development environment, but you can pretty much follow the same instructions everywhere. Just install the software dependencies as needed.

Configuring AWS Route 53

On the dashboard, select “Route 53” under “Networking & Content Delivery”. You can also type “route 53” on the search field. You’ll be redirected to AWS Route 53’s dashboard.

Now, on the sidebar, click on “Hosted Zones”.

You’ll need a domain for this, so you have a few options:

1. Use a domain you already have and it’s not being used (e.g. fnando.com)
2. Use a subdomain on a existing domain that’s being used (e.g. dev.fnando.com).
3. Buy a new domain, maybe one of those fancy .dev, which convey exactly what you’re doing (e.g. fnando.dev).

I decided to buy yet another domain and went with option #3, just because it’s shorter, specially when doing wildcard domains (something.dev.fnando.com vs something.fnando.dev). It looks nicer too! 🤓

Once you create your hosted zone, you have to configure your domain and point its DNS to AWS Route 53. The hosts you’ll need are defined under the record type NS. Go to your domain provider and set this up. I use Namecheap, so this is how you do it:

Back to AWS Route 53. Let’s create two A records that point your DNS to your development machine, in this case the loopback address 127.0.0.1.

The first record will handle fnando.dev. Click on “Create Record Set”, choose “A - IPv4 address” under the record type and set the value to 127.0.0.1. Make sure you don’t type anything under the name; otherwise, you’d be pointing a subdomain instead.

The second record will handle wildcard subdomains. Click on “Create Record Set” once again, choose “A - IPv4 address”, but this time use * as the record name. The value should be 127.0.0.1, just like before.

And the waiting game starts. You now have to wait until your DNS is propagated completely, but that shouldn’t take long. You can check it using dig on the command-line.

$ dig +short fnando.dev A
127.0.0.1

$ dig +short '*.fnando.dev' A
127.0.0.1

While you wait, you can set up a new AWS credential restricted to this domain. Before we move on, look at your browser’s url: you’ll need the zone id, so copy this value or write it down somewhere.

Now, let’s create the user and a policy. This can be done on AWS IAM, so search for this option under the services menu.

On the sidebar, click on “Policies”, then “Create Policy”.

Use the JSON below as your policy. Remember to replace YOUR_ZONE_ID with your zone id.

{
  "Version": "2012-10-17",
  "Id": "letsencrypt-mac policy",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["route53:ListHostedZones", "route53:GetChange"],
      "Resource": ["*"]
    },
    {
      "Effect": "Allow",
      "Action": ["route53:ChangeResourceRecordSets"],
      "Resource": ["arn:aws:route53:::hostedzone/YOUR_ZONE_ID"]
    }
  ]
}

Now, click on “Review policy”. Give it a recognizable name and click on “Create policy”.

It’s time to create a new user. On the sidebar, click on “Users” and then “Add User”. Give it a name like letsencrypt-mac, or something that describes your machine. You’ll also have to select “Programmatic Access” under “Access type”.

Click “Next”. Now we’re going to select the policy we’ve created a few steps before. Click on “Attach existing policies directly” and search for your policy, in this case letsencrypt-mac.

Click “Next: Tags”, then “Next: Review”. Finally, click “Create User”.

This step is important: you’ll be presented with your access and secret keys. Save both of them somewhere safe, like your password manager.

As far as AWS goes, you’re all set up. Now, let’s configure certbot, the command-line interface that’ll interact with Let’s Encrypt.

Configuring certbot

Since I’m a macOS user, I use homebrew. To install certbot, run brew install certbot. You can also find instruction for other system on certbot’s website.

$ brew install certbot
==> Downloading https://homebrew.bintray.com/bottles/certbot-1.4.0.catalina.bottle.tar.gz
Already downloaded: /Users/fnando/Library/Caches/Homebrew/downloads/f25750b88db0e526ac7fce38587eade58ef847892744acd31091a7d8fa4cdda4--certbot-1.4.0.catalina.bottle.tar.gz
==> Pouring certbot-1.4.0.catalina.bottle.tar.gz
🍺  /usr/local/Cellar/certbot/1.4.0: 1,451 files, 12.5MB

To automatically issue certificates that are validated against AWS Route 53’s DNS, we need to install a certbot plugin called certbot-dns-route53. We can Python’s pip.

$ pip3 install certbot-dns-route53
...
Installing collected packages: setuptools, zope.interface, pycparser, cffi, six, cryptography, PyOpenSSL, josepy, pytz, pyrfc3339, urllib3, certifi, chardet, idna, requests, requests-toolbelt, acme, docutils, python-dateutil, jmespath, botocore, s3transfer, boto3, parsedatetime, configobj, ConfigArgParse, distro, zope.deprecation, zope.event, zope.hookable, zope.proxy, zope.deferredimport, zope.component, certbot, certbot-dns-route53
Successfully installed ConfigArgParse-1.2.3 PyOpenSSL-19.1.0 acme-1.4.0 boto3-1.13.16 botocore-1.16.16 certbot-1.4.0 certbot-dns-route53-1.4.0 certifi-2020.4.5.1 cffi-1.14.0 chardet-3.0.4 configobj-5.0.6 cryptography-2.9.2 distro-1.5.0 docutils-0.15.2 idna-2.9 jmespath-0.10.0 josepy-1.3.0 parsedatetime-2.5 pycparser-2.20 pyrfc3339-1.1 python-dateutil-2.8.1 pytz-2020.1 requests-2.23.0 requests-toolbelt-0.9.1 s3transfer-0.3.3 setuptools-46.4.0 six-1.15.0 urllib3-1.25.9 zope.component-4.6.1 zope.deferredimport-4.3.1 zope.deprecation-4.4.0 zope.event-4.4 zope.hookable-5.0.1 zope.interface-5.1.0 zope.proxy-4.3.5

You can verify that certbot can see the plugin by running certbot plugins.

$ certbot plugins

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* dns-route53
Description: Obtain certificates using a DNS TXT record (if you are using AWS
Route53 for DNS).
Interfaces: IAuthenticator, IPlugin
Entry point: dns-route53 =
certbot_dns_route53._internal.dns_route53:Authenticator

* standalone
Description: Spin up a temporary webserver
Interfaces: IAuthenticator, IPlugin
Entry point: standalone = certbot._internal.plugins.standalone:Authenticator

* webroot
Description: Place files in webroot directory
Interfaces: IAuthenticator, IPlugin
Entry point: webroot = certbot._internal.plugins.webroot:Authenticator
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Now, let’s generate the certificates. The first thing to know is that you need to export your AWS credentials as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. It’s up to you how you want to manage these variables. Personally, I like adding them to ~/.zsh/user.sh, which is then loaded by my ~/.zshrc file. For this article, I’ll just export them before using them.

$ export AWS_ACCESS_KEY_ID=AKIAY7V6RRKVYA3Z4MGA
$ export AWS_SECRET_ACCESS_KEY='REDACTED_SECRET'

To generate a certificate, use the command certbot certonly. Notice that I’m specifying local directories; this is required if you don’t want to use sudo. After the process is complete, the certificate will be saved to ~/local/letsencrypt/live/fnando.dev. If you’re not sure if everything is set up accordingly, use the switch --dry-run; this will run certbot on their staging environment, which has a higher limit for failures. In production, you will be blocked from generating new certificates for a hour after a certain number of failures.

certbot certonly \
-n \
--agree-tos \
--email user@example.com \
-d fnando.dev \
-d '*.fnando.dev' \
--dns-route53 \
--preferred-challenges=dns \
--logs-dir /tmp/letsencrypt \
--config-dir ~/local/letsencrypt \
--work-dir /tmp/letsencrypt

Once the command finishes running, you’ll see something like this:

Saving debug log to /tmp/letsencrypt/letsencrypt.log
Found credentials in environment variables.
Plugins selected: Authenticator dns-route53, Installer None
Obtaining a new certificate
Performing the following challenges:
dns-01 challenge for fnando.dev
dns-01 challenge for fnando.dev
Waiting for verification...
Cleaning up challenges
Non-standard path(s), might not work with crontab installed by your operating system package manager

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /Users/fnando/local/letsencrypt/live/fnando.dev/fullchain.pem
   Your key file has been saved at:
   /Users/fnando/local/letsencrypt/live/fnando.dev/privkey.pem
   Your cert will expire on 2020-08-23. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot
   again. To non-interactively renew *all* of your certificates, run
   "certbot renew"
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le

This is all we need to do. When your certificates are about to expire, you’ll receive an email from Let’s Encrypt.

You’ll receive an reminder to renew your certificates via email. To renew your certificates, just run the same command above (i.e. certbot certonly).

certbot certonly \
-d fnando.dev \
-d '*.fnando.dev' \
--dns-route53 \
--preferred-challenges=dns \
--logs-dir /tmp/letsencrypt \
--config-dir ~/local/letsencrypt \
--work-dir /tmp/letsencrypt

Saving debug log to /tmp/letsencrypt.log
Plugins selected: Authenticator dns-route53, Installer None
Cert is due for renewal, auto-renewing...
Renewing an existing certificate
Performing the following challenges:
dns-01 challenge for fnando.dev
dns-01 challenge for fnando.dev
Waiting 30 seconds for DNS changes to propagate
Waiting for verification...
Cleaning up challenges

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /Users/fnando/local/letsencrypt/live/fnando.dev/fullchain.pem
   Your key file has been saved at:
   /Users/fnando/local/letsencrypt/live/fnando.dev/privkey.pem
   Your cert will expire on 2021-01-29. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot
   again. To non-interactively renew *all* of your certificates, run
   "certbot renew"
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le

Once it’s done, remember to restart the webserver.

Configuring NGINX

Once again, we can install NGINX using homebrew. Just run the command brew install nginx.

$ brew install nginx
==> Downloading https://homebrew.bintray.com/bottles/nginx-1.17.10.catalina.bottle.tar.gz
Already downloaded: /Users/fnando/Library/Caches/Homebrew/downloads/d7118d9cc53ef3be545ac049f7e50aa30f2378f673aa925702deaa6117fb403c--nginx-1.17.10.catalina.bottle.tar.gz
==> Pouring nginx-1.17.10.catalina.bottle.tar.gz
==> Caveats
Docroot is: /usr/local/var/www

The default port has been set in /usr/local/etc/nginx/nginx.conf to 8080 so that
nginx can run without sudo.

nginx will load all files in /usr/local/etc/nginx/servers/.

To have launchd start nginx now and restart at login:
  brew services start nginx
Or, if you don't want/need a background service you can just run:
  nginx
==> Summary
🍺  /usr/local/Cellar/nginx/1.17.10: 25 files, 2.1MB

Given that I develop web applications all the time, I like starting NGINX on boot. To do it so, run the command sudo brew services start nginx, and homebrew will take care of copying the launch file to /Library/LaunchDaemons/homebrew.mxcl.nginx.plist.

$ sudo brew services start nginx
Warning: Taking root:admin ownership of some nginx paths:
  /usr/local/Cellar/nginx/1.17.10/bin
  /usr/local/Cellar/nginx/1.17.10/bin/nginx
  /usr/local/opt/nginx
  /usr/local/opt/nginx/bin
  /usr/local/var/homebrew/linked/nginx
This will require manual removal of these paths using `sudo rm` on
brew upgrade/reinstall/uninstall.
Warning: nginx must be run as non-root to start at user login!
==> Successfully started `nginx` (label: homebrew.mxcl.nginx)

Yeah, I know… sudo. But that’s how you can hit https://fnando.dev instead of having to specify a non-privileged port. Another thing you could do is setting up /usr/local permission to the group admin, so it’s up to you.

Your NGINX configuration must be added to /usr/local/etc/nginx/servers/. I like to use the apex domain name (i.e. the domain name without subdomain) as the file name, so I’m going to create a /usr/local/etc/nginx/servers/fnando.dev.conf file with the content below.

upstream fnando_dev {
  server 127.0.0.1:3000 max_fails=0;
  server 127.0.0.1:4567 max_fails=0;
  server 127.0.0.1:5000 max_fails=0;
  server 127.0.0.1:5001 max_fails=0;
  server 127.0.0.1:9292 max_fails=0;
  server 127.0.0.1:9393 max_fails=0;
}

server {
  listen              80;
  listen              443 ssl;
  server_name         fnando.dev;

  ssl_certificate     /Users/fnando/local/letsencrypt/live/fnando.dev/fullchain.pem;
  ssl_certificate_key /Users/fnando/local/letsencrypt/live/fnando.dev/privkey.pem;

  ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
  ssl_ciphers         HIGH:!aNULL:!MD5;

  location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_redirect off;
    proxy_pass http://fnando_dev;
  }
}

server {
  listen              80;
  listen              443 ssl;
  server_name         *.fnando.dev;

  ssl_certificate     /Users/fnando/local/letsencrypt/live/fnando.dev/fullchain.pem;
  ssl_certificate_key /Users/fnando/local/letsencrypt/live/fnando.dev/privkey.pem;

  ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
  ssl_ciphers         HIGH:!aNULL:!MD5;

  location / {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_redirect off;
    proxy_pass http://fnando_dev;
  }
}

Notice that you cannot use ~ to indicate your home directory, so use the full path instead. Another thing is that you can specify any number of servers on the upstream statement, so make sure your framework’s port is listed there.

Now, restart the server with sudo brew services restart nginx.

$ brew services restart nginx
Stopping `nginx`... (might take a while)
==> Successfully stopped `nginx` (label: homebrew.mxcl.nginx)
==> Successfully started `nginx` (label: homebrew.mxcl.nginx)

If you’re all set up, you can hit your application on your custom domain, like https://fnando.dev. To quickly test it, start your web application and hit that url.

As you can see, this is a 100% valid certificate.

And subdomains work just fine. 😎

Wrapping up

You may be wondering why would you develop using HTTPS, and the answer is that many things require HTTPS, like webauthn. You can check a full list of features that require secure context on Mozilla’s website.

I tried all sort of combinations in the past, but this is the best option by far. No hacks, no crazy “add certificate roots to keychain” setups. Thanks, Let’s Encrypt.

Are there any benefits on using dark mode?

When you read about dark mode, you often see “easy on the eyes” or “energy efficiency” being mentioned. Truth is, to be energy efficient you need OLED/AMOLED screens which are only available on newer high-end devices.

• iPhone X or newer.
• Samsung Galaxy S10 or newer.
• Google Pixel 3 or newer.
• Huawei P30huawei-p30 or newer.

If you’re using LCD or another type of screen, changing colors won’t do much for your battery life. Most people won’t benefit from the energy efficiency aspect of dark modes at all.

But what about health? It certainly is better, right? Well… unfortunately, we still don’t have enough scientific data to assert that dark mode is better. What we know for sure is that the time we spend looking at screens is the main factor to eye strain. The less, the better.

Some doctors also mention that a higher contrast (either way) is more important than using either mode. And some doctors mention that dark mode can be more damaging for people with astigmatism.

I personally don’t like dark mode at all when using dark background with light text (i.e. black background with white text); I have that annoying feeling of burnt image that takes a minute or so to disappear. And the opposite is also true for some people. And without serious researches about this subject we can only talk by experience.

Now, I think the biggest advantage of dark mode is when you’re using your phone in a low light room, but you would be better off not using your phone right before going to sleep anyway, right?

Browse support

How well supported is dark mode on today’s browsers? To detect whether a browser is running on a dark mode device or not, you’ll need support for (prefers-color-scheme: dark) media query, available on the following devices.

• macOS Safari 13 or newer.
• iOS Safari 13.2 or newer.
• Android Browser 76 or newer.
• Chrome for Android 78 or newer.
• Firefox for Android 68 or newer.
• Opera 62 or newer.
• Chrome 76 or newer.
• Firefox 67 or newer.
• Microsoft Edge 76 or newer.

Yeah, I know… this is stupid versioning in action and I shouldn’t have added them anyway. What you need to know is that Safari 13 is very, very new. And so is the support for this media query on every other browser. From the business perspective, it doesn’t make sense to spend your designer’s time on this task, but you’re going to do it anyway, aren’t you? In this case, this is how you can define the CSS.

body {
  color: #333;
  background: #fff;
}

@media screen and (prefers-color-scheme: dark) {
  body {
    background: #2d3239;
    color: #75715e;
  }

  h1 {
    color: #e9d970;
  }
}

You can easily alternate between light and dark mode using Safari’s Web Inspector. I couldn’t find such option on Chrome yet, but we’ll have something similar sooner or later. This example can be found here.

I know what you’re thinking… the CSS can easily get out of hand. And you’re right! Unless you use variables. More specifically, CSS variables.

Creating manageable themes with CSS variables

The trick to organize your CSS is to use variables. To define a variable, you can use the --variable-name: value format.

:root {
  --page-background: #fff;
}

body {
  background: var(--page-background);
}

That simple. Now, how can we define both of our themes using variables? First, declare your light theme without any media query, like the following:

:root {
  --page-background: #fff;
  --page-title: #333;
  --page-text: #333;
}

body {
  background: var(--page-background);
  color: var(--page-text);
}

h1 {
  color: var(--page-title);
}

Now, adding the dark theme is as simple as wrapping the sample properties in a media query. The whole CSS code looks like this:

:root {
  --page-background: #fff;
  --page-title: #333;
  --page-text: #333;
}

@media screen and (prefers-color-scheme: dark) {
  :root {
    --page-background: #2d3239;
    --page-title: #e9d970;
    --page-text: #75715e;
  }
}

body {
  background: var(--page-background);
  color: var(--page-text);
}

h1 {
  color: var(--page-title);
}

You can see this example here. You can define any properties to tweak your theme including (but not limited to) background images, borders, shadows, and filters.

Dark mode images and videos

It’s not uncommon to have bright images/videos all over your page. One nice trick is using filters to reduce the brightness of <img> and <video>. You can try a combination of opacity and grayscale filters. Add --image-grayscale and --image-opacity variables and tweak it as you wish:

:root {
  --page-background: #fff;
  --page-title: #333;
  --page-text: #333;
  --image-grayscale: 0;
  --image-opacity: 100%;
}

@media screen and (prefers-color-scheme: dark) {
  :root {
    --page-background: #2d3239;
    --page-title: #e9d970;
    --page-text: #75715e;
    --image-grayscale: 50%;
    --image-opacity: 60%;
  }
}

img,
video {
  filter: grayscale(var(--image-grayscale)) opacity(var(--image-opacity));
}

You can see this example here. This trick won’t work everywhere and may requiring wrapping images in a container. Eventually, you’ll need a different image. That’s where <picture> comes in.

The <picture> element supports media query matchers. So, in case you want to specify a different logo for dark mode, you can use a different <source>. If there are no suitable matches or if the browser doesn’t support the <picture> element, then the default src attribute is selected.

Let’s say that instead of rendering that same image using filters, you wanted to render a totally different darker image.

<picture>
  <source srcset="beach.jpg" media="(prefers-color-scheme: dark)" />
  <img src="pool.jpg" />
</picture>

As for the CSS, you can remove everything related to filters. I’ll leave this as an exercise for you. The end result can be seen here.

In some cases, you may use an embedded embedded SVG and change the colors. It works great for things like flat icons, logos, and that sort of thing, but sometimes you just have to render a different image. Let’s add a logo that can adapt to dark mode.

It’s important to know is that, to style <svg> elements you have to actual render it on your HTML markup. Referencing it through an <img> tag won’t allow any styles on the rendering SVG. With that said, the SVG we’re using looks like this:

<svg
  id="logo"
  width="250px"
  height="55px"
  viewBox="0 0 250 55"
  version="1.1"
  xmlns="http://www.w3.org/2000/svg"
  xmlns:xlink="http://www.w3.org/1999/xlink"
>
  <g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
    <g id="logo">
      <path d="..." id="background" fill="#0091FF"></path>
      <path d="..." id="letter" fill="#FFD700" fill-rule="nonzero"></path>
      <path d="..." id="words" fill="#45638B" fill-rule="nonzero"></path>
    </g>
  </g>
</svg>

The colors applied to this SVG are the light mode colors, and by doing that we’re only required to style the dark mode. This is the updated CSS with the SVG styling changes.

@media screen and (prefers-color-scheme: dark) {
  :root {
    --page-background: #2d3239;
    --page-title: #e9d970;
    --page-text: #75715e;

    --logo-background: #4d5866;
    --logo-words: #fff;
  }

  #logo--words {
    fill: var(--logo-words);
  }

  #logo--background {
    fill: var(--logo-background);
  }
}

You can check this example here.

Alternatively, you could have used currentColor as the value of fill and stroke properties. This way, you can change all referenced colors by either setting the SVG’s color property or the inherited color. This approach works extremely well with line icons.

The example above generates a new color every time the button is clicked and sets the <body> element’s color with document.body.style.color = newColor.

Dark mode JavaScript

You may need to do operations that require detecting dark mode as well, like rendering charts. For that you’ll need to use window.matchMedia. The detection is fairly simple.

function isDarkMode() {
  return (
    window.matchMedia &&
    window.matchMedia("(prefers-color-scheme: dark)").matches
  );
}

function renderCanvas() {
  const theme = isDarkMode()
    ? { background: "#4d5866", border: "#7091ba" }
    : { background: "#ffffff", border: "#000" };

  const canvas = document.querySelector("canvas");
  const ctx = canvas.getContext("2d");
  const x = 15;
  const y = 15;
  const width = canvas.width - x * 2;
  const height = canvas.height - y * 2;

  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.lineWidth = 5;
  ctx.strokeStyle = theme.border;
  ctx.strokeRect(x, y, width, height);
  ctx.fillStyle = theme.background;
  ctx.fillRect(x, y, width, height);
}

renderCanvas();

As you can see, all you have to do is conditionally define your theme once your media matcher detects the dark mode. You can see this example here.

Now, if we switch from one mode to the other (you may also have configured your computer to automatically do it for you), you would see the wrong colors being rendered. To re-render the canvas we can use MediaQueryList.addListener to respond to the change.

const darkModeMatcher =
  window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)");

function isDarkMode() {
  return darkModeMatcher && darkModeMatcher.matches;
}

function onDarkModeChange(callback) {
  if (!darkModeMatcher) {
    return;
  }

  darkModeMatcher.addListener(({ matches }) => callback(matches));
}

function renderCanvas(useDarkTheme) {
  const theme = useDarkTheme
    ? { background: "#4d5866", border: "#7091ba" }
    : { background: "#ffffff", border: "#000" };

  const canvas = document.querySelector("canvas");
  const ctx = canvas.getContext("2d");
  const x = 15;
  const y = 15;
  const width = canvas.width - x * 2;
  const height = canvas.height - y * 2;

  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.lineWidth = 5;
  ctx.strokeStyle = theme.border;
  ctx.strokeRect(x, y, width, height);
  ctx.fillStyle = theme.background;
  ctx.fillRect(x, y, width, height);
}

renderCanvas(isDarkMode());
onDarkModeChange(renderCanvas);

This will make sure the function renderCanvas is called whenever the mode changes. You can see this example here.

And that pretty ends what you need to know about the technical aspects of supporting dark mode in the web.

Wrapping up

Dark mode is the latest trend in tech, no doubt about it. And even without having any serious research backing its so-called “dark mode benefits”, you may consider doing it for the sake of your customers’ happiness. The technical aspects are quite simple, but don’t fool yourself: creating dark themes is a very challenging process, specially when it comes to art direction for all assets (including images and video).

Another thing to consider is whether you should automatically switch to dark mode or use a configurable setting on your site. The latter is very simple to implement by setting a class on an element (e.g. <html data-theme="dark-mode">), but you’d have to manually execute scripts and change images/videos in case you switched from one mode to the other. Either that, or not bothering at all, which would be (probably) fine in most cases.

React Native is the go-to platform if you’re versed in React and need to develop mobile applications. Instead of using a hybrid approach like several projects out there, React Native aims to develop native applications with the tooling we already use in web development.

For the most part, this approach works perfectly, specially if you’re part of small team and lack the resources to develop full native code for both Apple and Android devices, but you need to be aware of its pros and cons, as in any other decision you have to make. Fortunately, Airbnb published a very nice article covering this subject, so make sure you read it.

And after doing your own reserch, you decided that React Native will work just fine for your needs, so now what? Well, this article will show how to get your app up and running on simulators for both iOS and Android devices, as well as how to set up your project.

Installing Xcode

To use iOS simulators, you’ll need a Mac. You may be able to run your app using services like Appetize (which I haven’t tested), but given that my main development environment is macOS, this is what I’ll focus on this article.

Many web developers out there are used to installing only the command-line tools, without the Xcode IDE, so they can build extensions or even use homebrew. To use iOS simulators, you’ll need the full thing, so go to the App Store and install Xcode.

This may take a while. When is done, open Xcode and install the extra components.

Now, you can install the iOS simulators. Go to “Preferences > Components” and download as many simulators as you want. I usually install only the latest version, but that’s on you and how far back you want to support.

As far as Xcode goes, you’re done! Now, let’s set up the Android emulator.

Installing Android Studio

Android’s ecosystem is different than Apple’s. First, you can install several third party emulators, some free, some paid. If you don’t want to choose, just use Android Studio, the official IDE.

After downloading Android Studio, move the app to your /Applications folder.

Now, open the app and follow the instructions. If you don’t have an Android SDK available, you’ll see a screen like the following:

Just click on “Next” when Android Studio will install it for you.

When is done, you be presented with a welcome screen.

Go to “Configure > SDK Manager”, then head to “SDK Tools”. Click on the checkbox to install the Build Tools, which will be used by React Native command-line tools. Click in “Apply” to install it.

Now, notice the Android SDK Location available on the image above. You’ll need this value to define an environment variable on the terminal. This is where things get tricky because you may have configured your terminal different than mine, but in general lines, you’ll have to do one of the following:

• If you use bash, add the following lines to ~/.bashrc.
• If you use zsh, add the following lines to ~/.zshrc.

export JAVA_HOME="/Applications/Android Studio.app/Contents/jre/jdk/Contents/Home"
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"

Restart your terminal to reload your configuration. You can check your configurations like the following:

$ echo $JAVA_HOME
/Applications/Android Studio.app/Contents/jre/jdk/Contents/Home

$ echo $ANDROID_HOME
/Users/fnando/Library/Android/sdk

$ which java
/Applications/Android Studio.app/Contents/jre/jdk/Contents/Home/bin/java

$ which adb
/Users/fnando/Library/Android/sdk/platform-tools/adb

$ which emulator
/Users/fnando/Library/Android/sdk/emulator/emulator

If you see anything too far from the above output, make sure you added the export lines to the correct files and restarted your terminal.

Finally, you can create a virtual device. Back to the welcome screen, go to “Configure > AVD Manager”.

Click on “Create Virtual Device” and select a device definition. In this example I’m selecting Pixel 3.

When you’re done, click on “Next”. Now you have to choose which Android version you’re going to use. You can go with the latest stable version available, which right now is Android Pie. Make sure you click the “Download” link.

After downloading the system image, click on “Next” once more. You’ll be presented with the device profile you’re creating. Just click “Finish”.

Now you’re back to the list of virtual devices available on your computer and you can always create more.

To start the emulator, click the play button available under the “Actions” column. Always remember to start the emulator by clicking the play button; otherwise, you’ll see a message like No connected devices! when trying to run React Native on the Android emulator.

You can also start the emulator from the command-line. All you have to do is using the emulator command.

$ emulator -list-avds
Pixel_3_API_28

$ emulator -avd 'Pixel_3_API_28'
emulator: INFO: boot completed
emulator: INFO: boot time 34488 ms
emulator: Increasing screen off timeout, logcat buffer size to 2M.

Congrats! You’re done with configuring emulators. Now, let’s spin up a sample app and run it on both simulators.

Configuring React Native

The official documentation recommends installing react-native-cli globally, but I avoid installing global packages. We’re going to use npx to generate the app skeleton.

$ npx react-native-cli init sample
...

✨  Done in 5.90s.

  Run instructions for iOS:
    • cd /Users/fnando/Projects/sample && react-native run-ios
    - or -
    • Open ios/sample.xcodeproj in Xcode
    • Hit the Run button

  Run instructions for Android:
    • Have an Android emulator running (quickest way to get started), or a device connected.
    • cd /Users/fnando/Projects/sample && react-native run-android

Go to the projects directory with cd sample and run react-native run-ios. This will compile the app, install it on the emulator and run a separate tab with Metro, the JavaScript bundler for React Native developed by Facebook.

$ react-native run-ios
...
info + exit 0

info

info ** BUILD SUCCEEDED **


info Installing build/sample/Build/Products/Debug-iphonesimulator/sample.app
info Launching org.reactjs.native.example.sample
org.reactjs.native.example.sample: 5043

This is the tab you should keep an eye on because any errors while running your app will be outputted to it. After everything is up and running, you’ll be able to see the sample app running on the iOS simulator.

Great! What about Android simulator? Make sure you have the virtual device running (remember, from the Android Studio’s welcome screen, choose “Configure > AVD Manager”, then press the play button). You can check for running devices by executing adb devices.

$ adb devices
List of devices attached
emulator-5554 device

Now, you can run react-native run-android. This will also compile a bunch of stuff and initialize the emulator.

$ react-native run-android
...

BUILD SUCCESSFUL in 14s
26 actionable tasks: 26 executed
info Running /Users/fnando/Library/Android/sdk/platform-tools/adb -s emulator-5554 reverse tcp:8081 tcp:8081
info Starting the app on emulator-5554 (/Users/fnando/Library/Android/sdk/platform-tools/adb -s emulator-5554 shell am start -n com.sample/com.sample.MainActivity)...
Starting: Intent { cmp=com.sample/.MainActivity }

You’ll be able to see the app running on the Android simulator if everything went smoothly.

Running physical devices

At some point you’re better off testing your apps on physical devices. This can help you fix bad user experience that wouldn’t bother on simulators.

Running the app on your iPhone

To run your app on the iPhone, open ios/sample.xcodeproj on Xcode. You can use open ios/sample.xcodeproj to open this file from your terminal.

First, you have to select a developer profile. Click on the project name and go to the target you’re building (in this case, sample). Change the bundle identifier to your own domain, otherwise you won’t be able to build the project. Then click “Add Account”, enter your Apple ID and password, and select your name under the dropdown. You may also have to select your developer account for the sampleTests target.

Connect your iPhone to the computer and click the simulator selector.

Your device will be available on the top of the list.

Finally, click the “Build and Run” button, or press cmd-R. This will install and open the app on your iPhone.

Running the app on your Android

I didn’t have an Android device, but decided to buy one to test the app on the real thing. After some research, I decided to buy a Xiaomi Mi A2 which costed me around $170 on Amazon. It’s a very nice device, even for daily usage. The good thing about it is that it comes with stock Android, and not the shitty modified version that some companies ship (looking at you, Samsung).

First, make sure Developer Options is enabled. Here, things can get tricky. Different devices can be activated differently. In my case, I had to go to “Settings > About phone” and tap the Build number 7 times in order to activate the developer mode. Then go to “Settings > System > Advanced > Developer Options” and activate “USB Debugging”.

To verify that your device is ready, run adb devices on your terminal.

$ adb devices
List of devices attached
bbb5cc28  device

Now, run react-native run-android. This command will install and open the app on your Android device.

Using TypeScript

This step is optional, but if you’re planning to release your app as an open-source project you may consider using TypeScript, the typed language that compiles down to JavaScript, created by Microsoft.

For new projects, all you have to do is running the generator with --template typescript.

$ npx react-native-cli init sample --template typescript
...
✨  Done in 4.96s.

  Run instructions for iOS:
    • cd /Users/fnando/Projects/sample_ts && react-native run-ios
    - or -
    • Open ios/sample_ts.xcodeproj in Xcode
    • Hit the Run button

  Run instructions for Android:
    • Have an Android emulator running (quickest way to get started), or a device connected.
    • cd /Users/fnando/Projects/sample_ts && react-native run-android

For existing projects, you’ll need to manually configure everything that the TypeScript template provides. I won’t cover this migration process here, so make sure you read the article published on the official blog.

Wrapping up

Despite all the efforts on developing the ecosystem, React Native is still immature and you’ll find that developing apps can be challenging. But even with all these difficulties, I consider React Native the best solution for small companies/teams that need to develop native apps.

Before deep diving into React Native, ask yourself if a PWA is a viable solution. Unfortunaly, PWA comes with its own challenges, like a different mindset for installing apps and inconsistencies between Android and iOS, as well as several device limitations, but it may be a good first step towards mobiles apps when responsive web is not enough, but React Native is too much.

To increase the compatibility level, we had to use things like es5-shim, which conditionally checked if a feature was available, adding a polyfill if the browser didn’t implement it.

And then the first pre-processors came in, like CoffeeScript. You could write different constructions, that were compiled to code that the browsers could actually understand.

Interestingly, Brendan Eich announced in 2009 a new JavaScript version called Harmony, which is now called ES2015¹. The first drafts were published in 2011, but the final specification was released in June of 2015.

ES2015 has so many new features:

• Class definition
• String interpolation
• Fat arrow functions
• More!

Browsers are implementing ES2015 in a fast pace, but it’ll take some time until we can actually use it. Maybe years. Fortunately, we have Babel.js. We can use all these new features today without worrying with browser compatibility.

Babel.js² is just a pre-processor. You write code that uses these new features (and more), which will be exported as code that browsers can understand, even those that don’t fully understand ES2015.

Using Babel.js with Asset Pipeline

There are several ways you can use to precompile your JavaScript code. Some people use Babel’s CLI. Some people prefer builders like Grunt or Gulp to automate the compilation process. But if you’re using Ruby on Rails you’re more likely to use Asset Pipeline for front-end assets compilation. And this is, in my opinion, the easiest way of using Babel, believe it or not.

Unfortunately there’s no built-in support on the stable release of Sprockets, so you’ll have to use a pre-release version.

The transpilation is performed by babel-schmooze-sprockets. It vendors several Babel extensions so that you can use Babel without having to deal with NPM on your application (you’ll still need Node.js though).

Update your Gemfile to include these dependencies.

source "https://rubygems.org"

gem "rails", "4.2.6"
gem "sqlite3"
gem "uglifier", ">= 1.3.0"

gem "sprockets", "~> 4.x"
gem "babel-schmooze-sprockets"

gem "turbolinks", "~> 5.x"
gem "jquery-rails"

That’s it! Now all .es6 files will be compiled using Babel. Create a file at app/assets/javascripts/hello.es6 with the following code:

class Hello {
  constructor() {
    alert("Hello!");
  }
}

new Hello();

Make sure you’re loading hello.es6 at app/assets/javascripts/application.js. You also need to load Babel helpers; they’ll be used to reduce the amount of generated code.

//= require babel
//= require_tree .
//= require_self

Now if you access the page on your browser, you’ll see an alert box like this:

If you want the new module system, you still have some things to configure.

Using ES2015 modules

ES2015 introduced module support; instead of defining your code in the global scope, you can use a scope per file. Importing modules is pretty straightforward:

import Foo from "foo";

This will load Foo from foo.js. One single file can export several units (functions, objects, anything you want), and you don’t have to load everything at once, pretty much like Python.

Babel has no idea of how these modules should be exported, and by default, will use the CommonJS format, which can’t be used by the browser, so we’ll use another approach.

The easiest way is using AMD, and for this we’ll use almond. You can install almond with whatever you’re using for managing packages; in this article I’ll use http://rails-assets.org, a bower-to-rubygems converter. Update your Gemfile like the following:

source "https://rubygems.org"

gem "rails", "4.2.6"
gem "sqlite3"
gem "uglifier", ">= 1.3.0"

gem "sprockets", "~> 4.x"
gem "babel-schmooze-sprockets"

gem "turbolinks", "~> 5.x"
gem "jquery-rails"

source "https://rails-assets.org" do
  gem "rails-assets-almond"
end

Finally, update app/assets/javascripts/application.js so it loads almond.

//= require turbolinks
//= require almond
//= require jquery
//= require_tree .
//= require_self

Notice that Turbolinks must be loaded before Almond; this happens because Turbolinks is an anonymous AMD module. For more information, check the section “Almond.js gotcha”, later on this article.

Now you have to think about the execution process. Are you going to use some code dispatcher? Or execute code based on the view that is being rendered? Are you going to create your own execution mechanism? The answer depends on your own workflow, so I’m not going to give you too many alternatives here.

We’re going to create a boot script that uses the controller and action names to execute the JavaScript you need for that specific page. Just add the require call to your app/assets/javascripts/application.js file.

//= require turbolinks
//= require almond
//= require jquery
//= require_tree .
//= require_self

require(["application/boot"]);

You have to create app/assets/javascripts/application/boot.es6. I’ll listen to some events, like DOM’s ready and Turbolinks’ turbolinks:load.

import $ from "jquery";

function runner() {
  var path = $("body").data("route");

  // Load script for this page.
  // We should use System.import, but it's not worth the trouble, so
  // let's use almond's require instead.
  try {
    require([path], onload, null, true);
  } catch (error) {
    handleError(error);
  }
}

function onload(mod) {
  // Assign the default module.
  var Page = mod.default;

  // Instantiate the page, passing <body> as the root element.
  var page = new Page($(document.body));

  // Set up page and run scripts for it.
  if (page.setup) {
    page.setup();
  }

  page.run();
}

// Handles exception.
function handleError(error) {
  if (error.message.match(/undefined missing/)) {
    console.warn("missing module:", error.message.split(" ").pop());
  } else {
    throw error;
  }
}

$(window)
  .ready(runner)
  .on("turbolinks:load", runner);

This script needs a data-route property property on your <body> element. You can add something like the following to your layout file (e.g. app/views/layouts/application.html.erb). You can use the following helper method:

# app/helpers/application_helper.rb
module ApplicationHelper
  ACTION_ALIASES = {
    "update" => "edit",
    "create" => "new"
  }

  def js_route
    action_name = ACTION_ALIASES[controller.action_name] || controller.action_name
    controller_name = controller.class.name.underscore.gsub("_controller", "")

    "#{controller_name}/#{action_name}"
  end
end

And then:

<body data-route="application/pages/<%= js_route %>">

Now let’s create a class that will be executed when the template is rendered. We’ll use the site controller and home action as example. For this you’ll need to create the app/assets/javascripts/application/pages/site/home.es6 file.

export default class Home {
  constructor(root) {
    this.root = root;
  }

  setup() {
    // add event listeners
    console.log("-> setting up listeners and whatnot");
  }

  run() {
    // trigger initial action (e.g. perform http requests)
    console.log("-> perform initial actions");
  }
}

Note that we’re exporting the Home class as the default module. This is the module that will be used when you have something like import Home from 'application/pages/home';.

Also note that we’re defining the Home#constructor method; this is the method that is executed when the class is instantiated.

I said this before, but class definition is one of the things I like the most. Compare it with the constructor function form:

function Home(root) {
  this.root = root;
}

Home.prototype.setup = function() {
  // add listeners
};

Home.prototype.run = function() {
  // initial execution
};

They’re are similar, but using the class keyword makes closer to what we use in other languages. Here’s how you would write the same class in Ruby:

class Home
  def initialize(root)
    @root = root
  end

  def setup
  end

  def run
  end
end

ES2015 has other niceties. To discover what’s new, I recommend the Exploring ES6 book, which you can read for free.

Almond.js gotcha

There is one gotcha when using Almond; all modules must be explicitly named. This means that libraries like qunit won’t work out of the box because they’re anonymous modules. To solve this problem, you should load the library before loading Almond and then exporting the module yourself.

//= require qunit
//= require almond

define("qunit", function() {
  return QUnit;
});

The problem of doing this is that the library won’t detect AMD support and will export global variables, but I still prefer this behavior over compiling code with an optimizer like r.js or a library that integrates that into Rails.

Wrapping up

Using ES2015 today is a viable option. With Babel you can use all these new features without worrying with browser compatibility. The integration with Asset Pipeline make things easier, even for those that don’t fully grasp the Node.js ecosystem.

There’s a working repository available at Github.

This article shows how you can set up your own uptime checker and run it on Heroku for $7/month.

About uptime_checker

I created uptime_checker, which has less than 500 lines. The main features are:

• Several notification mechanisms (Telegram, Twitter’s Direct Message, E-mail, Slack, Hipchat, and more)
• Easy to set up on Heroku
• Easy to define the sites that will be monitored

The idea is pretty simple: hit the urls you define every 30s (configurable) and see if the site returns the expected status code. You can also check if the response contains a string. If the status/body is not what you expected, it notifies you.

Running uptime_check on Heroku is really easy and you won’t need more than a few minutes, so let’s do it.

Setting up uptime_checker

First, you have to fork the repository, since you have to create your own branch with a configuration file. Go to Github and hit the “Fork” button.

Now, clone the repository and create a new branch: I’ll call it personal in this article.

$ git clone git@github.com:<your username>/uptime_checker.yml
$ cd uptime_checker
$ git checkout -B personal

Copy the sample configuration file.

$ cp checkers.yml.sample checkers.yml

Open the checkers.yml file. This file is where you define all the sites that must be monitored. It supports ERB, so you can render dynamic variables. Here’s is my own configuration file.

notify: &notify
  - twitter: fnando
  - email: fnando.vieira@gmail.com
  - stdout: ~
  - telegram: -97517324
  - noti: <%= ENV["NOTI_FNANDO"] %>

checkers:
  - name: Codeplane
    url: https://codeplane.com/
    notify: *notify
    status: 200

  - name: Codeplane
    url: https://codeplane.com.br/
    notify: *notify
    status: 200

  - name: Hellobits
    url: http://hellobits.com/
    notify: *notify
    status: 200

  - name: HOWTO
    url: http://howtocode.com.br/
    notify: *notify
    status: 200

  - name: Nando Vieira
    url: http://nandovieira.com/
    notify: *notify
    status: 200

  - name: Nando Vieira
    url: https://nandovieira.com.br/
    notify: *notify
    status: 200

  - name: Presentta
    url: https://presentta.com.br/
    notify: *notify
    status: 200

To avoid repeating the notifiers, I’m using the shared block trick. You can have different notifications for each site you’re monitoring if you need.

Notice that I’m expecting those sites to respond with a 200 status code, but you can also check if the response has some given text.

checkers:
  - name: Example
    url: http://example.com
    notify: *notify
    status: 200
    body: Some string

After you’re done, commit your changes.

$ git add .
$ git commit -m "Add checkers."
$ git push origin personal

Deploying to Heroku

Deploying uptime_checker to Heroku is the easiest way you can have this running. Assuming you already Heroku configured, create a new application.

$ heroku create

Redis is required, so we need to add the add-on.

$ heroku addons:create heroku-redis

To receive e-mail notifications, you’ll also need Sendgrid.

heroku addons:create sendgrid:starter

I use Noti. If you check the checkers example above, you’ll see that I’m using a NOTI_FNANDO environment variable. Let’s set that on Heroku:

$ heroku config:set NOTI_FNANDO=fc17d63d-5d3e-4532-98ed-b8047f0d5bc9

Now it’s time to deploy! Since we’ll deploy the personal branch, you have to use the following command:

$ git push heroku personal:master

This means that the personal branch will be pushed as Heroku’s master.

To run this 24/7 ($7/mo), we have to scale up our worker.

$ heroku ps:scale worker=1
$ heroku dyno:type worker=hobby

And we’re done! You can check the logs with heroku logs --tail.

app[worker.1]: enabled_notifiers="email, noti, stdout, telegram, twitter" time="2016-01-29T12:40:28Z"
app[worker.1]: message="starting check" url="https://presentta.com.br/" time="2016-01-29T12:40:28Z"
app[worker.1]: message="starting check" url="https://nandovieira.com.br/" time="2016-01-29T12:40:28Z"
app[worker.1]: message="starting check" url="http://nandovieira.com/" time="2016-01-29T12:40:28Z"
app[worker.1]: message="starting check" url="http://howtocode.com.br/" time="2016-01-29T12:40:28Z"
app[worker.1]: message="starting check" url="http://hellobits.com/" time="2016-01-29T12:40:28Z"
app[worker.1]: url="https://codeplane.com/" message="check finished" status="no changes" time="2016-01-29T12:40:28Z"
app[worker.1]: url="https://codeplane.com.br/" message="check finished" status="no changes" time="2016-01-29T12:40:28Z"
app[worker.1]: url="http://howtocode.com.br/" message="check finished" status="no changes" time="2016-01-29T12:40:28Z"
app[worker.1]: url="https://nandovieira.com.br/" message="check finished" status="no changes" time="2016-01-29T12:40:28Z"
app[worker.1]: url="https://presentta.com.br/" message="check finished" status="no changes" time="2016-01-29T12:40:28Z"

If you’re not into Heroku, you can also deploy it to a VPS. If you already know how to deploy a Rails application, you won’t have any problem. Since this involves too much things, I leave this as an exercise to the reader.

Keeping up with master

You may want to keep up with master, getting all the fixes and new features (if any). The workflow for updating your branch is pretty simple.

First, switch off to master and pull all the changes.

$ git checkout master
$ git pull

Then switch back to personal and apply master‘s onto it.

$ git checkout personal
$ git rebase master

Now, deploy the repository.

$ git push heroku personal:master -f

Wrapping up

That’s it! If you have any suggestions or need help, just open an issue.

In this article we’ll see how to use the utilities provided by Rails, so that your system can handle dates correctly.

How Ruby works

Ruby has basically two different classes for handling dates: Date and Time¹. You can generate dates by parsing strings or using individual attributes that represent the year, hour, month, and so on.

require "time"

Time.parse("Dec 8 2015 10:19")
#=> 2015-12-08 10:19:00 -0200

Date.parse("Dec 8 2015")
#=> #<Date: 2015-12-08>

Time.new(2015, 12, 8, 10, 19)
#=> 2015-12-08 10:19:00 -0200

Date.new(2015, 12, 8)
#=> #<Date: 2015-12-08>

Every date calculation must be performed manually. Let’s say you want to advance one hour; all you have to do is add 3600 seconds to the date.

time = Time.now
#=> 2015-12-08 10:26:40 -0200

time + 3600
#=> 2015-12-08 11:26:40 -0200

Most calculations are easy to implement, but things get complex when you have to consider time zones.

Working with time zones

To set the time zone in a Ruby script, you have to set the TZ environment variable. This variable is not defined in most systems, but that will depend on how your server is configured. Older POSIX systems used this variable but this done by /etc/localtime now.

This is how Ruby behaves with and without the TZ variable.

ENV["TZ"]
#=> nil

Time.now
#=> 2015-12-08 10:30:00 -0200

ENV["TZ"] = "America/Los_Angeles"
#=> "America/Los_Angeles"

Time.now
#=> 2015-12-08 04:30:14 -0800

The date command, available in *nix systems, also use the TZ variable, changing how the date is presented in a user session.

$ date
Tue Dec  8 09:37:12 BRST 2015

$ export TZ=America/Los_Angeles

$ date
Tue Dec  8 03:37:27 PST 2015

The problem is that not every software out there will use this variable automatically (or use it at all). PostgreSQL won’t use the TZ variable, preferring the timezone configuration².

SELECT current_setting('timezone');
#=> Brazil/East

You’re better off avoiding the time zone in all pieces of your infrastructure; instead of using a specific time zone, just go with Etc/UTC. This will free you from problems related to DST and cron jobs. It will also be easier to define how different systems will work with dates and communicate. The time zone presentation should be the application’s responsibility.

How Ruby on Rails works

To define the time zone in Ruby on Rails application use the environment configuration file or create an initializer.

# config/initializers/time_zone.rb
Time.zone = "America/Sao_Paulo"

Ruby on Rails can have a time zone configuration per application, totally ignoring the TZ environment variable, but this behavior has some implications.

First, Ruby won’t consider Rails’ time zone configuration. This means that if your system is using the America/Sao_Paulo time zone and your application is using America/Los_Angeles, Ruby will still consider the former configuration.

Time.now.zone
#=> "BRST"

Time.zone = "America/Los_Angeles"
#=> "America/Los_Angeles"

Time.now.zone
#=> "BRST"

To generate dates that knows about the time zone, you should use methods defined by the ActiveSupport library. These methods will generate objects from the ActiveSupport::TimeWithZone³ class. There are a large number of methods and their usage will depend on what you want to accomplish.

Time.zone.now
#=> Tue, 08 Dec 2015 03:37:57 PST -08:00

Time.zone.today
#=> Tue, 08 Dec 2015

Time.current
#=> Tue, 08 Dec 2015 03:38:17 PST -08:00

1.hour.ago
#=> Tue, 08 Dec 2015 02:38:28 PST -08:00

1.day.from_now
#=> Wed, 09 Dec 2015 03:38:36 PST -08:00

Date.yesterday
#=> Mon, 07 Dec 2015

Date.tomorrow
#=> Wed, 09 Dec 2015

The general guidelines are:

• Use Time.current instead of Time.now.
• Use Date.current instead of Date.today.

Notice that Time.current will ignore the time zone information if your application doesn’t set it; the same will happen to Date.current, as you can see in ActiveSupport’s implementation:

# activesupport-4.2.5/lib/active_support/core_ext/time/calculations.rb
# line 30
class Time
  def current
    ::Time.zone ? ::Time.zone.now : ::Time.now
  end
end

# activesupport-4.2.5/lib/active_support/core_ext/date/calculations.rb
# line 46
class Date
  def current
    ::Time.zone ? ::Time.zone.today : ::Date.today
  end
end

You can always use Time.zone.today and Time.zone.now for a deterministic result.

Dealing with Daylight Saving Time

ActiveSupport uses the TZInfo gem so it can know about time zones. This gem will load all this information from your operating system; in Ubuntu, this information comes from the tzdata package.

This means that keeping your server up-to-date will provide fresh information about DST and all time zones from all around the world.

The code below shows how the dates know about DST, considering Brazil’s DST for 2016.

Time.zone.parse('2015-10-17').dst?
#=> false

Time.zone.parse('2015-10-18').dst?
#=> true

Time.zone.parse('2016-02-20').dst?
#=> true

Time.zone.parse('2016-02-21').dst?
#=> false

Sometimes you have to parse dates and DST can bring unexpected consequences. Recently I had to integrate some user-provided dates in calendar and the biggest challenge was displaying future dates, considering time zones and DST.

Turns out the solution is simple; when parsing dates, ignore the time zone information from the string and use the Time.use_zone.

Time.current
#=> Mon, 07 Dec 2015 18:57:51 BRST -02:00

Time.use_zone("America/Sao_Paulo") do
  starts_at = Time.zone.parse("2016-03-05 10:00")
  #=> Sat, 05 Mar 2016 10:00:00 BRT -03:00

  ends_at = Time.zone.parse("2016-03-05 17:00")
  #=> Sat, 05 Mar 2016 17:00:00 BRT -03:00
end

How dates are persisted

ActiveRecord will persist dates in UTC (Coordinated Universal Time). This behavior is defined by the ActiveRecord::Base.default_timezone and ActiveRecord::Base.time_zone_aware_attributes properties.

ActiveRecord::Base.default_timezone
#=> :utc

ActiveRecord::Base.time_zone_aware_attributes
#=> true

Every time you persist an date attribute to the database, ActiveRecord will convert it to UTC. And after loading a record, ActiveRecord will do the other way around, converting the date back to the time zone defined in your application⁴.

Notice that dates can be off by some hours if you use Date.today or Time.now.

Time.zone = "America/Los_Angeles"
#=> "America/Los_Angeles"

Time.now.beginning_of_day.utc
#=> 2015-12-08 02:00:00 UTC

Time.current.beginning_of_day.utc
#=> 2015-12-08 08:00:00 UTC

This happens because Time.now ignores the time zone defined by the application and will use the system’s one (in this case BRST-0200). That’s why is extremely important for you to use ActiveSupport methods, like I said before.

Since ActiveRecord assumes that all dates are persisted as UTC, you can also end up with wrongs dates if you update database records from outside the application. PostgreSQL has a column type that knows about time zones and will convert dates before persisting it. Unfortunately Rails doesn’t support time with time zone, but you can easily add it to your application by creating an initializer with the following code:

# config/initializers/active_record.rb
ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::
  NATIVE_DATABASE_TYPES[:datetime] = {name: "timestamp with time zone"}

Querying your database

We already know that ActiveRecord assumes your dates are stored as UTC. To make your queries work as expected, all you have to do is use dates that have this time zone knowledge (like Time.current) and the library will do the right thing.

Article.where("published_at >= ?", Time.current)

Remember that dates generated by 1.day.ago and Date.current.beginning_of_month will consider the time zone, so feel free to use them.

Parsing dates sent by users

When parsing dates you must also consider time zones. Ruby has the methods Time.parse and Date.parse, but they ignore this information. In this case you should use Time.zone.parse or your dates can be off by a few hours.

Time.parse("8:47am Dec 7th, 2015").utc
#=> 2015-12-07 10:47:00 UTC

Time.zone.parse("8:47am Dec 7th, 2015").utc
#=> 2015-12-07 16:47:00 UTC

If you have numbers that represent the date, use Time.zone.local instead of Time.new.

Time.new(2015, 12, 7, 8, 47, 0).utc
#=> 2015-12-07 10:47:00 UTC

Time.zone.local(2015, 12, 7, 8, 47, 0).utc
#=> 2015-12-07 16:47:00 UTC

Finally, use Time.zone.at if you have a Unix timestamp.

Time.zone.at(1449506820)
#=> 2015-12-07 16:47:00 UTC

To set the time zone for an execution context, use the method Time.use_zone, which sets the specified time zone only while running the block.

Time.zone = "America/Sao_Paulo"
#=> "America/Sao_Paulo"

now_in_sao_paulo = Time.current
#=> Tue, 08 Dec 2015 09:40:31 BRST -02:00

now_in_los_angeles = Time.use_zone("America/Los_Angeles") do
  Time.current
end
#=> Tue, 08 Dec 2015 03:40:31 PST -08:00

now_in_sao_paulo.utc
#=> 2015-12-08 11:40:31 UTC

now_in_los_angeles.utc
#=> 2015-12-08 11:40:31 UTC

now_in_sao_paulo.to_i == now_in_los_angeles.to_i
#=> true

You can use this method on your controller so you can set the user’s time zone.

class ApplicationController < ActionController::Base
  around_action :set_timezone, if: :logged_in?

  private

  def set_timezone(&action)
    Time.use_zone(current_user.time_zone, &action)
  end
end

Working with dates in JavaScript

You may need to communicate with your Rails application from JavaScript. The best way of dealing with dates is by using moment.js.

Use the Time#iso8601 method to send formatted dates to JavaScript; this will generate something like 2015-12-07T19:25:45Z. You can then use moment.js to convert this string into a JavaScript Date object.

var date = moment("2015-12-07T19:25:45Z");
//=> Mon Dec 07 2015 17:25:45 GMT-0200 (BRST)

date.format("MMM DD, YYYY - h:mma");
//=> Dec 07, 2015 - 5:25pm

Notice that moment.js will use the browser’s time zone (BRST-0200 in my case); if you need to convert the date to a different time zone, use momentjs-timezone.

Wrapping up

If you application deals with dates, most notably date calculations, understand how Rails’ date handling works is essential. To make your life easier, just follow these rules:

• Use Etc/UTC as your server’s time zone.
• Always define the time zone in your Rails application, even if it’s Etc/UTC.
• Deal with time zone presentation on your application’s layer.
• Use Time.current and Date.current to retrieve the current date.
• Use Time.zone.parse to convert string into dates.
• Convert Date em ActiveSupport::TimeWithZone for comparison, like date.in_time_zone == Time.current.beginning_of_day.

Resources

• Dealing With Time Zones Using Rails and Postgres
• Dealing with timezones effectively in Rails
• Handling Dates & Timezones in Ruby & Rails
• Handling Time Zones in Rails
• How Rails and MySQL are handling time zones
• The Exhaustive Guide to Rails Time Zones
• The Worst Server Setup Mistake You Can Make
• Working with time zones in Ruby on Rails

This article has been updated. Read Using ES2015 with Asset Pipeline on Ruby on Rails instead.

JavaScript is all new. Until recently, we had no new features. The last significant update was back in 2009, with ES5‘s release. And you couldn’t use all features due to browser incompatibility.

To increase the compatibility level, we had to use things like es5-shim, which conditionally checked if a feature was available, adding a polyfill if the browser didn’t implement it.

And then the first pre-processors came in, like CoffeeScript. You could write different constructions, that were compiled to code that the browsers could actually understand.

Interestingly, Brendan Eich announced in 2009 a new JavaScript version called Harmony¹, which is now called ES6. The first drafts were published in 2011, but the final specification was released in June of this year.

ES6 has so many new features:

• Class definition
• String interpolation
• Fat arrow functions
• More!

Browsers are implementing new features in a fast pace, but it would still take some time until we could actually use ES6. Maybe years. Fortunately, we have Babel.js. We can use all these new features today without worrying with browser compatibility.

Babel.js² is just a pre-processor. You write code that uses these new features, which will be exported as code that browsers can understand, even those that don’t fully understand ES6.

Using Babel.js

To install Babel make sure you have Node.js installed. Then you can install Babel using NPM.

$ npm install babel -g

You can now use babel command to compile your JavaScript files. You can enable the watch mode, which will automatically compile modified files. The following example with watch src and export files to dist.

$ babel --watch --out-dir=dist src

One of the features I like the most is the new class definition, which abstracts constructor functions. In the following example I create a User class that receives two arguments in the initialization.

class User {
  constructor(name, email) {
    this.name = name;
    this.email = email;
  }
}

After processing this file with Babel, this is what we have:

'use strict';

var _createClass = (function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ('value' in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; })();

function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError('Cannot call a class as a function'); } }

var User = (function () {
  function User() {
    _classCallCheck(this, User);
  }

  _createClass(User, [{
    key: 'construct',
    value: function construct(name, email) {
      this.name = name;
      this.email = email;
    }
  }]);

  return User;
})();

var user = new User('John', 'john@example.com');

console.log('name:', user.name);
console.log('email:', user.email);

Note that Babel generates all the required code for supporting the class definition. Alternatively, you can use --external-helpers to generate code that uses helpers (helpers can be generated with the babel-external-helpers command).

$ babel --external-helpers --watch --out-dir=dist src

Now all supporting code will use the babelHelpers object.

'use strict';

var User = (function () {
  function User() {
    babelHelpers.classCallCheck(this, User);
  }

  babelHelpers.createClass(User, [{
    key: 'construct',
    value: function construct(name, email) {
      this.name = name;
      this.email = email;
    }
  }]);
  return User;
})();

var user = new User('John', 'john@example.com');

console.log('name:', user.name);
console.log('email:', user.email);

Using Babel.js with Asset Pipeline

Instead of using Babel’s CLI, some people prefer builders like Grunt or Gulp to automate the compilation process. But if you’re using Ruby on Rails you’re more likely to use Asset Pipeline for front-end assets compilation.

Unfortunately there’s no built-in support on the stable release of Sprockets. But if you like to live on the edge³, you can use the master branch.

Update your Gemfile to include these dependencies.

source 'https://rubygems.org'

gem 'rails', '4.2.4'
gem 'sqlite3'
gem 'uglifier', '>= 1.3.0'

gem 'sass-rails', github: 'rails/sass-rails', branch: 'master'
gem 'sprockets-rails', github: 'rails/sprockets-rails', branch: 'master'
gem 'sprockets', github: 'rails/sprockets', branch: 'master'
gem 'babel-transpiler'

gem 'turbolinks'
gem 'jquery-rails'

That’s it! Now all .es6 files will be compiled using Babel. Create a file at app/assets/javascripts/hello.es6 with the following code:

class Hello {
  constructor() {
    alert('Hello!');
  }
}

new Hello();

Make sure you’re loading hello.es6 at app/assets/javascripts/application.js.

//= require_tree .
//= require_self

Now if you access the page on your browser, you’ll see an alert box like this:

If you want the new module system, you still have some things to configure.

Using ES6 modules

ES6 introduced module support; instead of defining your code in the global scope, you can use a scope per file. Importing modules is pretty straightforward:

import Foo from 'foo';

This will load Foo from foo.js. One single file can export several units (functions, objects, anything you want), and you don’t have to load everything at once, pretty much like Python.

Babel has no idea of how these modules should be exported, and by default, will use the CommonJS format, which can’t be used by the browser, so we’ll use another approach.

The easiest way is using AMD, and for this we’ll use almond. You can install almond with whatever you’re using for managing packages; in this article I’ll use http://rails-assets.org, a bower-to-rubygems converter. Update your Gemfile like the following:

source 'https://rubygems.org'

gem 'rails', '4.2.4'
gem 'sqlite3'
gem 'uglifier', '>= 1.3.0'

gem 'sass-rails', github: 'rails/sass-rails', branch: 'master'
gem 'sprockets-rails', github: 'rails/sprockets-rails', branch: 'master'
gem 'sprockets', github: 'rails/sprockets', branch: 'master'
gem 'babel-transpiler'

gem 'turbolinks'
gem 'jquery-rails'

source 'https://rails-assets.org' do
  gem 'rails-assets-almond'
end

You also have to configure Babel; just create a file at config/initializers/babel.rb with the following code:

Rails.application.config.assets.configure do |env|
  babel = Sprockets::BabelProcessor.new(
    'modules'    => 'amd',
    'moduleIds'  => true
  )
  env.register_transformer 'application/ecmascript-6', 'application/javascript', babel
end

Finally, update app/assets/javascripts/application.js so it loads almond.

//= require almond
//= require jquery
//= require turbolinks
//= require_tree .
//= require_self

Now you have to think about the execution process. Are you going to use some code dispatcher? Or execute code based on the view that is being rendered? Are you going to create your own execution mechanism? The answer depends on your own workflow, so I’m not going to give you too many alternatives here.

We’re going to create a boot script that uses the controller and action names to execute the JavaScript you need for that specific page. Just add the require call to your app/assets/javascripts/application.js file.

//= require almond
//= require jquery
//= require turbolinks
//= require_tree .
//= require_self

require(['application/boot']);

You have to create app/assets/javascripts/application/boot.es6. I’ll listen to some events, like DOM’s ready and Turbolinks’ page load.

import $ from 'jquery';

function runner() {
  // All scripts must live in app/assets/javascripts/application/pages/**/*.es6.
  var path = $('body').data('route');

  // Load script for this page.
  // We should use System.import, but it's not worth the trouble, so
  // let's use almond's require instead.
  try {
    require([path], onload, null, true);
  } catch (error) {
    handleError(error);
  }
}

function onload(Page) {
  // Instantiate the page, passing <body> as the root element.
  var page = new Page($(document.body));

  // Set up page and run scripts for it.
  if (page.setup) {
    page.setup();
  }

  page.run();
}

// Handles exception.
function handleError(error) {
  if (error.message.match(/undefined missing/)) {
    console.warn('missing module:', error.message.split(' ').pop());
  } else {
    throw error;
  }
}

$(window)
  .ready(runner)
  .on('page:load', runner);

This script needs a data-route property property on your <body> element. You can add something like the following to your layout file (e.g. app/views/layouts/application.html.erb):

<body data-route="application/pages/<%= controller.controller_name %>/<%= controller.action_name %>">

Now let’s create a class that will be executed when the template is rendered. We’ll use the site controller and home action as example. For this you’ll need to create the app/assets/javascripts/application/pages/site/home.es6 file.

export default class Home {
  constructor(root) {
    this.root = root;
  }

  setup() {
    // add event listeners
    console.log('-> setting up listeners and whatnot');
  }

  run() {
    // trigger initial action (e.g. perform http requests)
    console.log('-> perform initial actions');
  }
}

Note that we’re exporting the Home class as the default module. This is the module that will be used when you have something like import Home from 'application/pages/home';.

Also note that we’re defining the Home#constructor method; this is the method that is executed when the class is instantiated.

I said this before, but class definition is one of the things I like the most. Compare it with the constructor function form:

function Home(root) {
  this.root = root;
}

Home.prototype.setup = function() {
  // add listeners
};

Home.prototype.run = function() {
  // initial execution
};

They’re are similar, but using the class keyword makes closer to what we use in other languages. Here’s how you would write the same class in Ruby:

class Home
  def initialize(root)
    @root = root
  end

  def setup
  end

  def run
  end
end

ES6 has other niceties. To discover what’s new, I recommend the Exploring ES6 book, which you can read for free.

Almond.js gotcha

There is one gotcha when using Almond; all modules must be explicitly named. This means that libraries like qunit won’t work out of the box because they’re anonymous modules. To solve this problem, you should load the library before loading Almond and then exporting the module yourself.

//= require qunit
//= require almond

define('qunit', function() {
    return QUnit;
});