The Remote team has been working hard to deliver the launch of our Global Employee API, designed to help HR and payroll companies leverage Remote’s powerful global infrastructure to help more businesses hire globally. By taking the international infrastructure that has allowed us to offer a superior experience for businesses and teams around the world and making it available to developers, we’re able to afford so many more businesses the chance to expand their global team. 

In this article, we want to focus on the journey we took to migrate from built-in documentation to using OpenAPI schemas. You will learn why this was so important, and we’ll explain the benefits of using OpenAPI for your Elixir projects. 

A large number of developers are working on the Remote platform, and our team continues to grow every month.

There are many different domains within the product, and different developers have different specialties, both for the domains and for the backend and frontend technologies powering them. This makes our internal APIs essential for effective communication.

We started by using Elixir's built-in documentation features to document our APIs. This served us well for a while. However, as our team grew, we needed more. A collection of issues began to surface that triggered our need for a better solution

The problems with relying on built-in documentation became more obvious, and they are familiar challenges for any team experiencing fast growth:

Maintaining example json responses, query parameters, and request bodies in @doc attributes: This involved copy/pasting json and keeping a list of query parameters.

Ensuring the documentation was up-to-date: at times the docs would go stale and not match the API, because this system relied on the team remembering to update whenever a change was made.

Exposing and browsing the documentation: including extra steps to build docs and opening and finding endpoints. Some developers are not as familiar with the Elixir tooling, another barrier to pass to get to the docs.

Thankfully, there is a better way to maintain API documentation. We want to explain how to simplify documentation management for a growing global team and reduce manual upkeep.

For introducing changes to the development process, we have an internal RFC (Request For Comments) process. In this case, we had two separate RFCs with some overlap around improving our API documentation. After some conversations, we opted to adopt OpenAPI specifications for our internal RESTful APIs.

OpenAPI is a specification for RESTful APIs. It's widely used and the Elixir ecosystem has good tooling for it. From the specification, you can then generate documentation. It has several other functions as well, like generating clients, servers, data validation, and more.

OpenAPI’s own introduction is quite comprehensive, but here's the TL;DR:

An OpenAPI specification can either be a yaml or json file.

You need to define a “Path” for every API endpoint.

Each Path can have multiple “Operations” (get, post, put, etc).

Each operation describes the parameters, payload, and possible server responses.

To make adding and editing specs more integrated to our normal development flow, we decided to use Open API Spex. Open API Spex is a library for Elixir to generate and serve the Open API Spec document from code.

To organize our specs, we mirror the Context structure of the Phoenix app.

The implementation of this has been intentionally gradual. The initial change started by writing specs for two controllers (six operations), with a bit of developer documentation on how to work with Open API Spex.

When working on functionality related to an endpoint, we add specs along the way. Sometimes, we add incomplete placeholder specs which we can later expand on.

Although we are not done yet, we're up to around 150 documented endpoints. Already our team is experiencing some tangible benefits, with cleaner alignment and less manual work leading to speedier delivery on critical projects.

Documentation is easy to find and browse, leading to less confusion about the APIs, fewer questions and a better async workflow.

We can test the specs! Now we can ensure our documentation is reliable and up to date, which ultimately reduces bugs.

We can provide mock data from the specs for the frontend, automatically. Less manual in this regard makes us faster as a collective.

We now have a single source of truth for API documentation!

This last result is such a win for our team and for Remote as a business.

The developer experience boost is significant. This new clear single source of truth makes it so much easier for our team to understand and deliver value. We are reducing the frustration involved in context shifting, which means less errors and faster delivery.

This solution is also more scalable, setting up our processes in the cleanest possible way for new starters - something of critical importance as the Remote team is growing so fast.

Open API means more transparency for Remote

More importantly, this move to migrate from built-in documentation to using OpenAPI schemas delivers on one our continual quest for Transparency; one of the fundamental values of Remote. To succeed in a Remote-first business, transparency is vital. 

Automation, documentation, and scalable processes are the lifeblood of our company. Indeed, any team trying to facilitate sustainable fast growth in a remote environment, either in an engineering team, or any other department, can benefit from more transparent work practices. At the very least, we’re confident that using OpenAPI for your Elixir projects will serve you well for the future.

How OpenAPI schemas can improve documentation, communication, and transparency

Open API Specifications: Documentation & Communication

Open API Specifications: Improving Documentation & Communication

At Remote, we constantly push ourselves to create the most secure, most flexible, and most dependable solutions for our customers. To accomplish this, we seek out the best tech talent in countries across the globe, no matter where that talent lives. We believe that only an international team can build the solutions the international market demands.

As part of our commitment to excellence in tech, we are delighted to announce that José Valim, the creator of the Elixir programming language and Chief Adoption Officer at Dashbit, is joining Remote as an advisor. José’s expertise and experience will be invaluable as we continue to build the top global employment solution on the planet.

Remote, José, and Elixir: the perfect combination

As Elixir’s creator, José is the ideal representative from the Elixir community to advise Remote on its use. We are excited to work together and tackle the challenges of global employment in the years to come.

“What attracted me to Remote is that they are tackling complex and exciting problems that are extremely relevant to today's world, and they are doing so in Elixir,” says José. “After talking to Marcelo (Remote's CTO), it is clear they are betting on the language in the long term, and I believe there are many opportunities for Remote and Elixir to grow together.”

Remote relies on Elixir to power our backend engineering. Over the last three years, Elixir has grown rapidly in both web and embedded markets to become one of the most respected and important new tools for developers around the world. We built Remote’s global employment solutions using Elixir to meet the highest standards of scalability, concurrency, and resiliency. 

The Elixir community is a wonderful group of people from around the world who are dedicated, welcoming, and highly active in pursuit of our shared tech goals. The learning curve for Elixir is low, which allows us to onboard new engineers quickly and get them working on meaningful projects. By building with Elixir, Remote will continue to move quickly and scale confidently to meet the needs of its customers.

From 2010 to 2014, José was a member of the Rails Core Team, where he received the Ruby Hero Award to recognize his critical work on open source projects. He created the Elixir programming language in 2011 and received the Erlang User of the Year award in 2015 for his contributions to the ecosystem. He has written three books on technical subjects and is a regular speaker at some of the world’s biggest technical conferences. He is an engineering graduate from Escola Politécnica de São Paulo in Brazil, and he earned his master’s in machine learning from Politecnico di Torino in Italy.

José also co-founded Plataformatec, a company acqui-hired by Nubank in 2020. He served as a technical advisor to Base, which was acquired by Zendesk in 2018. Today, he leads the Dashbit team in his role as CAO to help companies adopt and run Elixir throughout the world.

We are incredibly grateful and proud to have José join Remote as an advisor. No one achieves excellence without standing on the shoulders of giants, and José stands tall.

At Remote, we are building the future of remote work to make it easier for companies to employ top talent all over the world. That’s a big task. Building a platform to power that vision means we have to use every tool at our disposal as effectively as possible. Working alongside José and the Elixir community connects us to a powerful group of minds who will help us as we redefine what it means to work from anywhere.

Those connections have already begun to augment our capabilities, but the more we connect with great minds in tech, the more we look to bolster our own team. We are scaling our engineering team quickly, and our standards continue to climb as we meet the best engineering talent from all over the world.

If you would like to join us in our pursuit to democratize access to global talent, visit our careers page to see available openings. You can also follow me on Twitter to hear more about Remote’s approach to building great products and our collaboration with the Elixir community (and a few of my best bad jokes).

As we begin the new year with a growing team and new partnerships, we are excited to share with you what comes next. Please join us in welcoming José Valim as our new connection to the Elixir community and our latest ally in our quest to reimagine the possibilities of global employment.

Remote is delighted to announce that José Valim, the creator of the Elixir programming language and Chief Adoption Officer at Dashbit, is joining Remote as an advisor. José’s expertise and experience will be invaluable as we continue to build the top global employment solution on the planet.

Welcoming Elixir creator José Valim as an advisor to Remote

Every person has a unique way of thinking and, therefore, a unique way of coding. Developing a solution that makes sense to every dev on your team can be difficult, especially the problems become more complex. If you're trying to improve an Elixir codebase, the complexity can quickly become overwhelming.

You have several options to improve the readability and maintainability of your code: for example, the SOLID principles. In this blog post, though, I will show you a few Elixir features to help make your code cleaner and more readable.

We begin with a very powerful but underrated feature in Elixir that enables the developer to write multiple conditional statements, such as nested case statements in a cleaner way.

With can combine multiple clauses using pattern match. In case the right side of the operator, <- matches the term on the left-hand side the flow and continues to the next clause. If the terms don't match, it will skip to its else clause.

Whenever I'm writing a with statement, I like to start by defining the happy path and then handle all the possible errors (if needed).

with user when not is_nil(user) <- Accounts.get_user_by(%{name: "Pippin"}),
     false <- is_going_on_an_adventure?(user) do
		eat_second_breakfast(user)
else
  nil ->
    {:error, "User not found"}

  true ->
    {:error, "User is not in the Shire"}
end


We can only reach Pippin's end goal, which is to eat second breakfast, if all the other conditions are met.

We handled all unexpected errors gracefully in the else clause by setting custom error messages.

The function eat_second_breakfast/1 returns a tuple {:ok, result} or {:error, reason}.

This looks much cleaner than using multiple nested clauses, which makes the code easier to review.

Keep in mind that the else clause is not necessary if you don't need to handle the error when the pattern match fails.

with {:ok, user} <- fetch_user_by_name("Pedro Pascal"),
     {:ok, _} <- rescue_baby_yoda(user) do
   buy_new_suit(user)
end

....

defp fetch_user_by_name(name) do
  case Accounts.get_user_by(%{name: name}) do
    nil -> {:error, "User with name #{name} not found"}
    user -> {:ok, user}
  end
end


Here, all auxiliary functions return a tuple, and the with statement doesn't need to handle the error messages. This approach of returning the error in the auxiliary function is particularly helpful when we would have two functions returning the same value in the with statement. This is also less messy than adding the operation identifier on each with clause, like this:

with {:user, user} when not is_nil(user) <- {:user, Accounts.get_user_by(%{name: "Pippin"})},
     {:starship, starship} when not is_nil(starship) <- {:starship, Starships.get_starship(1)} do
   fly(user, starship)
else
  {:user, nil} ->
		{:error, "User not found"}

  {:starship, nil} ->
		{:error, "Starship not found"}
end


To finish this section, I'll illustrate how we can use with with Ecto.Repo.transaction/1.

Repo.transaction(fn ->
  with {:ok, payment} <- create_payment(%{user_id: user_id, starship_id: starship.id}),
       {:ok, _} <- update_starship(starship, %{owner_id: user_id}) do
    payment
  else
    {:error, reason} ->
      Repo.rollback(reason)
  end
end)


In the example above, if the update to the starship fails, the else clause will be executed and the transaction rolled back as expected.

For more details about with, read this documentation.

Improving readability through attribution with Elixir

Since Elixir is a functional language, it doesn't use references to objects like OOP languages. Therefore, every variable attribution is a memory copy, and we should develop taking that into consideration.

def find() do
  ...
 {:ok,
    {
       Accounts.get_user_by(%{name: "Aragorn"}),
       Accounts.get_user_by(%{name: "Legolas"}),
       Accounts.get_user_by(%{name: "Gimli"})
    }
 }
end


def find() do
  with {:ok, aragorn} <- fetch_user_by_name("Aragorn"),
       {:ok, legolas} <- fetch_user_by_name("Legolas"),
       {:ok, gimli} <- fetch_user_by_name("Gimli") do
    {:ok, {aragorn, legolas, gimli}}
  end
end
...

IconicTrio.find()


At Remote, we strive to keep our code as straightforward and simple as possible. Only after we achieve simplicity do we move on to making the code faster, if necessary. This way, we avoid wasting time over-optimizing code and can ship more code at a faster pace. These coding practices also help us maintain our focus on security and reliability.

Beyond following the conventions defined here, each team can also define its own naming convention to ensure everyone can get a basic understanding of what a function does just by reading the name.

For instance, when building user attributes:

# Instead of
attrs = attrs(attrs, user, opts)
# Do
user_attrs = **build_user_attrs**(attrs, user, opts)


Disclaimer: this is mostly a pet peeve of mine, but it's still good coding practice worth knowing.

When I'm programming, I want to make it easier for others (and my future self) to find pieces of code like aliases, requires, module attributes, etc. My teams have always followed this style guide for module attributes/directives ordering, but it's just a guide. Teams should discuss and decide what it's best for them based on their own unique needs.

I'm used to having module attributes and directives on top of the file, each type grouped together and sorted alphabetically within the group. For example:

alias App.{Accounts, Skills, Starships}
alias App.Accounts.ModuleA
**a**lias App.Skills.{ModuleA, ModuleB}


Following a structured and ordered approach for module attributes and directives helps you avoid duplicated definitions and allows you to find what you need faster, because you always know where to look.

Elixir ships with the mix task mix format, which allows you to format all your codebase with a single command. This is an awesome command to make sure your code is properly indented and avoid back and forth code reviews because you missed a space or an extra comma at the end of a list. The most popular code editors now support extensions that automatically run mix format on file save.

The mix task relies on the configs found in the file .formatter.exs, such as line_length and inputs (which describes the files to be used by the task). You can read more about it by visiting this resource.

Some people are against code comments. They believe code should be understandable enough to not need explanation or tests are the only documentation needed. In my humble opinion, code comments are essential to explain why we had to develop something in a particular way. This is useful for your future self and for team members when revisiting a part of your code/feature.

The more documented your code is, the more likely it is to be understandable by others and thus the easier it is to update. Using comments makes it less likely for your code to end up being considered legacy code just because others couldn't understand the repercussions of changing a file. Consider this example:

@doc """
  Rescues Baby Yoda by navigating to the planet Arvala-7 and then clears the
	encampment with the help of IG-11, neutralizing it in the process.

	We have to neutralize IG-11 because IG-11 is a bounty-hunter droid that
  intended to collect his prize money with Baby Yoda.
"""
def rescue_baby_yoda(mandalorian), do: ....


I hope you find this guide on improving your Elixir codebase to be helpful and informative. If you have any questions, feel free to reach out to me on Twitter @csilva_antonio. I'm always happy to help!

6 tips to improve your Elixir codebase

Practical tips to improve your Elixir codebase

Companies are catching on to the advantages of Kubernetes for development of their Platform-as-a-Service (PaaS) solutions. At Remote, we have just completed a successful transition to Kubernetes and would like to share our story to help others make the switch.

Different businesses have different needs, methodologies, and cultures, and not everyone grows in the same direction. As we grew, we knew we needed internal tools that would not only complement our processes but would fit within our philosophy of work. We use Kubernetes as a building block in our internal PaaS solution to abstract away infrastructure and provide our developers with smaller surfaces with which to deploy and manage their applications.

Kubernetes is only six years old, however, and many people who would benefit from its implementation aren't sure how to deploy, manage, and secure it correctly. This is why we decided to write these blog posts and best practices to help others make the switch quickly and safely.

At Remote, we believe everything we do should be documented and, if possible, automated. Code is automation and can act as documentation when simple and written well. So, we strongly believe in infrastructure-as-code and are heavy users of Terraform.

Remote is also a customer of Amazon Web Services (AWS), so examples in this and following posts will be infrastructure provisioned on AWS via Terraform.

When we jumped into this redesign, we had a few requirements:

Subnet resource segregation: publicly accessible resources such as load balancers, webservers, etc; privately accessible resources hidden behind load balancers and webservers, such as frontend or backend applications; privately accessible resources for use by applications such as databases, caches, search indices, etc.

IP Addressing - Maintain enough IPv4 addressing capacity for future scale. Each Kubernetes node, pod, and service will have its own IP address, and we should keep in mind that the number of services will increase.

Redundancy - Split logical subnets in groups of three, for use by three availability zones, for redundancy.

EKS Compatibility - Keep compatibility with EKS clusters in mind, which is the Kubernetes managed solution we wanted to use.

If you want to reproduce the implementation in this article, you will need a couple of tools:

Kubernetes clusters prefer to be laid on a flat network, with the same IP address space shared between Kubernetes nodes, masters, and pods running on them. This greatly simplifies networking from an operations standpoint, but it makes it difficult to properly segregate these networks from a security standpoint. That's why we strongly recommended an internal private network for all of these, with specific public endpoints exposed via ingress load balancers. Exposing services like this keeps public only the ones that should be public and private the ones that should not be publicly accessible.

The next level of segregation is to separate your applications from their databases, including SQL and NoSQL database systems, key value stores, caches, indexing systems, etc. These databases should live in a separate network of their own and should only be allowed to talk to applications.

Applications can then connect to databases and be contacted from inside the Kubernetes cluster, which has a single entry point in the form of a service (an Ingress Controller) that forwards external traffic to the internal Kubernetes services specified by the respective Kubernetes ingresses.

Public: Where our NAT gateways and load balancers live

Application: Where our Kubernetes cluster machines and pods are

Database: Where all of our databases stay

For reliability, we should also make our clusters multi-datacenter. On AWS, an Availability Zone (AZ) maps to a datacenter. We decided to go with three AZs. That effectively makes for three subnets per logical subnet, as you need to specify to which AZ a given subnet will correspond. That brings it to:

We created a Virtual Private Cloud (VPC) to hold all of these subnets. We picked 10.0.0.0/16 as the VPC IP range to maximize the number of IP addresses in our internal networks. Splitting this network into ranges for the subnets is left as an exercise to the reader. We can't divulge all of our network topology!

As previously mentioned, we at Remote are heavy users of Terraform as a tool to implement Infrastructure-as-Code (IaC). IaC allows you to define the end state that your infrastructure (i.e. cloud resources) should achieve as code and provides you with several good properties.

The value of attributes of resources (e.g. the CIDR block of a subnet) can be exported and re-used when defining other resources (e.g in an EC2 instance's Security Group), defining explicit dependencies between them. These dependencies can be represented as a dependency graph and acted upon the tool to allow for repeatable provisioning of resources.

Terraform Remote State allows us to export output values of Terraform runs and use them in other repositories, effectively abstracting away implementation details and exposing infrastructure as an API developers can use, without worrying about how resources are deployed. In a Terraform multi-repository architecture, such as the one we use at Remote, these remote states can help with passing data between runs of different repositories.

Terraform does a lot of type safety and format safety checks before running, allowing you to avoid errors when deploying your infrastructure. This helps you be more precise when automating.

Terraform code, when written well and structured, can act as documentation of the infrastructure itself.

But, this article is not a sales pitch for Terraform, we'll leave that for our friends at Hashicorp.

The following code provisions our main VPC and the subnets we listed in the Network Design section. Put this in a vpc.tf file and change out the ... with CIDR blocks that make sense for your use case.

Second: Define your NAT and internet gateways

The following code provisions an Internet Gateway so that resources in our subnets can access the internet. We also deploy our NAT Gateways here, which mediate access to and from the internet to our internal resources and, thus, are placed only in public subnets. We're also provisioning one elastic IP address per NAT Gateway so they are externally accessible on fixed IP addresses. Put this in a nat.tf file.

Now we have our different subnets, available in three different Availability Zones. How do we make them talk to each other?

We need resources in the app and db subnets to have access to the internet to fetch updates. To make this possible, we create and associate route tables. This tells the AWS network fabric what traffic to route and to where. In our case, we are defining two types of route tables: public and private. We have defined a public one, which will route external traffic directly to the internet while remaining capable of routing internal traffic to subnets in the VPC, and three private route tables, which will route external traffic to the NAT Gateway placed in the public subnet of their corresponding Availability Zone. Put this in a routes.tf file.

We know we will add databases, caches, and others to the db subnets. These subnet groups allow referencing to these subnets when we provision those databases. You may add other kinds of subnet groups that you use here. Put these in a subnet_groups.tf file.

We hope this article helps you begin to architect your Kubernetes network correctly. We believe this setup provides the best network scalability and segregation capabilities for the future of Remote, and it may work for your company, too.

See you in the next blog post, where we'll talk about spinning up the actual Kubernetes cluster using Elastic Kubernetes Service. If you have questions, feel free to reach out on Twitter!

Enterprise-Ready Kubernetes: Part 1 of our 'How to Architect for Kubernetes' Series

How to architect for Kubernetes: Part 1

Remote is pleased to announce that we have completed our migration to Kubernetes. In our mission to build a global infrastructure for global employment, we depend on advanced tools that allow us to build with the scale and flexibility that our customers need. This upgrade marks a step forward in our ability to develop and deploy our industry-leading solutions.

Kubernetes provides an open-source container orchestration system to eliminate many of the issues present in container-dependent development. By automating application deployment, scaling, and management, Kubernetes allows us to accelerate our development and deployment processes with greater visibility.

In short: Kubernetes gives Remote’s development team more power, more speed, and more flexibility, and we use those advantages to empower our customers.

Until now, Remote ran applications on AWS’s Elastic Container Service using AWS Fargate. This service offered some of the same functionality as Kubernetes, but as our needs and the needs of our customers became more complex, we wanted a system that provided us with more portability and greater control over our applications. With those needs in mind, Kubernetes was the obvious choice.

AWS Fargate made it possible for Remote to build our original infrastructure with both speed and security. As our team grew and we began to ship more frequently, our need to control more of the infrastructure and deployment process grew as well. While AWS Fargate and Kubernetes both work well with Remote’s just-in-time (JIT) engineering philosophy, our unique needs for control and back-end customization led us to make the switch.

Kubernetes appealed to us because it allows for full control of infrastructure, roll-out strategies, and portability. With AWS Fargate, we experienced issues with unpredictable rotation times, missing command line access to containers, and log output speed. Using Kubernetes, quick rotation times allow us to keep a close watch on the progress of our deployments. Access to the command line ensures that we can jump in and make time-sensitive changes when necessary. Thanks to Kuberenetes’ documentation and widespread community, we can work easily through complex configurations and integrations.

AWS Fargate helped us set the foundation, but Kubernetes provides more of the predictability, observability, and control we need to scale our product across the world.

To support the new Kubernetes setup, we use infrastructure-as-code practices and Terraform configurations that give us the power to rebuild Remote’s infrastructure if ever the need should arise. We also rebuilt our Continuous Integration pipelines (GitLab CI) from scratch to deploy our applications to Kubernetes. This allowed us to simplify our workflows, empowering our teams to deploy changes with more speed and fewer complications.

These changes did not affect how users engage with Remote’s solutions. On the contrary, they help us maintain the product reliability our customers have come to expect.

We are excited to share this milestone with our customers and partners. Kubernetes has brought new levels of clarity and efficiency to our continuous integration and deployment processes, and we expect to share more news about our processes and products in the months to come. Keep an eye on our blog for updates, and connect with us on Twitter or LinkedIn if you would like to ask questions about our move to Kubernetes.

Remote on Kubernetes: The future of our global infrastructure

We use Sass at Remote, especially the .scss syntax. Sass gives our team features that don’t exist yet in CSS, like nesting selectors, mixins, functions, variables (although CSS has now custom properties they have differences), which are great for productivity.

It’s a good opportunity, when starting a new project, to look for formatting, naming and architecture standards.

We’ve been using a pattern by Hugo Giraudel, the 7-1 Pattern in almost all of our previous projects and it’s being a good fit for all our needs. You can find more about it here.

Using this pattern you have all your sass partials in 7 different folders and a single file at root level that imports all folders. This is used to later compile everything to a single CSS stylesheet.

base/
components/
layout/
pages/
themes/
abstracts/
vendors/
main.scss

This has been our go-to architecture and we’re following almost all recommendations. However, there are some nuances that we felt the need to overcome and so we created our own approach to this architecture so that it could fit codebases of all sizes.

We didn’t like the idea of having a file importing every sass file on the project because we would get a big CSS file with all our code being used on every page and having a lot of unnecessary CSS being loaded.

There are only two folders that we need to import on any page, the abstracts and the base folder.

For these folders, we’ve created a _global.scss file where we’re importing all files inside.

/abstracts
  _functions.scss
  _variables.scss
  _mixins.scss
  _global.scss
/base
  _general.scss
  _fonts.scss
  _global.scss

// abstracts/_global.scss
@import 'variables';
@import 'functions';
@import 'mixins';

// base/_global.scss
@import '../abstracts/global';
@import 'general';
@import 'fonts';

Since we need the files in the abstracts folder in any scss file to be able to use the mixins, variables or functions, we can save some time and import the _global.scss in the abstracts folder in the _global.scss of the base folder. Without this, we would have to import abstracts _global on every single page.

We’re using webpack to generate multi entries and outputs to create a specific CSS file for each page and importing only what it needs. You can find more info on how to use webpack with Sass here. With this solution, we can create a sign-in.scss file in the page folder that will import all the defaults and specific components to be rendered on the page.

// sign-in.scss
// scss/ is an alias

@import 'scss/base/global';
@import 'scss/layout/header';
@import 'scss/layout/form';
@import 'scss/components/buttons';
@import 'scss/components/auth';
@import 'scss/components/loaders';

We’ve started following the folder structure that the 7-1 pattern suggests, but on all projects that we’ve worked with, none of them had the need for all the folders.

So, if you take an approach of using only what you need, independently if it’s a small or big codebase it only impacts the number of files.

/abstracts
  _functions.scss
  _global.scss
  _mixins.scss
  _variables.scss
/base
  _fonts.scss
  _general.scss
  _global.scss
  _typography.scss
/components
  _header.scss
  _form.scss
  _buttons.scss
  ...
/vendor
  _bootstrap.scss
  _normalize.scss
/pages
  auth.scss
  homepage.scss
  ...

The /abstracts folder contains all the sass helpers you can create to help you out on your project. This is all about sass tools, variables, mixins, functions, placeholders, etc.

We’re using the _global.scss to import all files so we don’t bloat other files with these imports.

The /base folder contains all the boilerplate of the project. It’s where we set the default styles, import custom fonts, set the default style for the headings, paragraphs, hyperlinks.

Following the component-based approach of Javascript frameworks like React, we treat everything a component. These are independent, reusable pieces of the UI and you can think of components like a navbar, a header or a button.

That’s why instead of using a layout folder for elements like a Footer or a Header, we create pages that are composed by components.

The /vendor folder contains all the third party files that the application needs. It can be a reset CSS file, bootstrap, anything you could think of.

If these files should be included in any page of the website, we import in /base/general.scss.

The /pages folder should contain the specific styles for each page with the filename being the name of the page. In our use case, we use webpack to create specific CSS files for each page and import all the default styles and the components that I need for each page. You can find more information on how we do this here.

This approach allows us to import only the code that the page needs and reduce the size of the file.

// billing.scss
@import 'scss/base/global';
@import 'scss/components/header';
@import 'scss/components/footer';
@import 'scss/components/form';

.billing {
  max-width: 640px;
  margin-top: pixelToRem(90px);

  &-section {
    margin-bottom: pixelToRem(60px);

    p {
      margin-top: pixelToRem(5px);
    }
  }
}

If you’re not using something like webpack to bundle and convert your javascript and sass/less files and you have a main.scss where you import everything, this approach allows you having a _global.scss file per folder importing all the other files and import these globals to your main file.

// main.scss
@import 'scss/abstracts/global';
@import 'scss/base/global';
@import 'scss/components/global';
@import 'scss/pages/global';
@import 'scss/vendor/global';

We hope you find this article helpful, as the 7-1 pattern was very useful to us. With the structural foundation for our SASS codebase and with a few tweaks here and there we got to a point where we’re finally happy with its productivity and organization.

We’d love to hear what you think about this and how we could further improve this approach!

We use Sass at Remote, especially the .scss syntax. Sass gives our team features that don't exist yet in CSS, like nesting selectors, mixins, functions, and variables (although CSS has now custom properties they have differences), which are great for productivity.

How to structure your Sass codebase

Following the trend of dark mode, I thought this would be a good challenge to create my first library and help developers add dark mode themes to their websites.

At Remote, specially in our blog, we thought it would be nice to add dark mode and so we implemented an initial version. The problem was that our initial implementation didn’t fit all our future use cases and because we’ve updated the project in Gatsby to use the new version of react, our implementation became stale.

Instead of taking time to implement something specifically for Gatsby and worrying about SSR, we decided to find and use a library that would take care of that for us. If you want to know where we’re using our time at Remote, check https://blog.remote.com/solving-global-employment-through-remote/ 😛.

But to use this technique in all React-based websites and using the Context API that allows us to access the state easily in all components was not possible . That’s were I’ve found a good niche to contribute.

So I built a library based on the Context API and React hooks which allows you to easily implement dark mode.

https://github.com/luisgserrano/react-dark-mode

As I said, this library uses the Context API so you should have at least React 16.3.0.

To help you out with styling your app, we detect if the user has requested the system to use a light or dark color theme (by using the prefers-color-scheme CSS media feature) and set this theme as a class of the body tag like <body class="dark">.

By having this, you can create different styles when the body tag as the css class dark or light.

Since we’re using the Context API you should add our provider on top of your top level component so that all the child components have access to this state.

You can use the context in any child component of the <Provider> and this context exposes the mode variable, which is the theme that can be light or dark and the toggleMode function which toggles the theme. When the mode changes, this component will re-render.

  import Provider, { useDarkmodeContext } from 'react-use-dark-mode';

  // Images
  import BlackLogo from './blackLogo.svg';
  import WhiteLogo from './WhiteLogo.svg';

  const Header = () => {
    const { mode, toggleMode } = useDarkmodeContext();

    function getLogo(theme) {
      return theme === "light" ? BlackLogo : WhiteLogo;
    }

    return (
      <header>
        <img src={getLogo(mode)} alt="Logo" />
        <button type="button" onClick={toggleMode}>Toggle darkmode</button>
      </header>
    );
  };

  ReactDOM.render(
    <Provider>
      <Header />
    </Provider>,
    document.getElementById('header')
  );

  :root {
    --textPrimaryColor: #000;
    --backgroundPrimaryColor: #fff;
  }

  body {
    color: var(--textPrimaryColor);
    background-color: var(--backgroundPrimaryColor);
  }

  body.dark {
    --textPrimaryColor: #fff;
    --backgroundPrimaryColor: #000;
  }

  .block__element {
    color: var(--textPrimaryColor);
  }

As you can see, you only need to add the CSS based on the theme and add a button to toggle the theme.

The benefit of this library is if you need to change something that you can’t with CSS and you’re using React, like in the example above where we had to change the src of an image based on the theme, you can now easily subscribe to the theme change and apply your custom behavior.

Overall, this has been an excellent experience to start in the world of open source, the feeling that someone is using your work and you’re helping someone building products with it is awesome.

I've built a simple React library that allows developers implement dark mode in their React-based websites, using the Context API.

How to add dark mode to your website

At Remote.com we’re heavy users of Phoenix Framework. As we make good progress to ship the new Remote.com there are a few tips and tricks we’re happy to share.

We’re using coherence as the backbone for our auth system. It’s quite easy and fast to setup.

Soon after you finish all requirements and setup procedures it’ll be time to get going and actually implement some auth flows.

If you already implemented your fair share of web systems, I’m sure the term and/or variable current_user is one you know all too well.

If that isn’t the case, well, in short, it’s typically a variable populated with a data structure or record identifying the user that originated the respective request.

A very common way to access this variable without having to fetch it explicitely from conn in every action of our controller is to override the action plug.

As a first attempt to simplify that, you can do the following:

defmodule MyApp.UserController do
  use MyApp.Web, :controller

  def action(%Plug.Conn{assigns: %{current_user: current_user}} = conn, _opts) do
    apply(__MODULE__, action_name(conn), [conn, conn.params, current_user])
  end

  def show(conn, _params, current_user) do
    render(conn, "show.html", logged_in: current_user)
  end

As you can see we now have a function called action which will override Phoenix’s controller default action/2 plug allowing us to inject custom arguments. More about this here.

Although this is a lot better, it’s still not very DRY as we’d need to replicate this function all over every single controller in which we need to access current_user.

At Remote.com, we're heavy users of Phoenix Framework. As we make good progress to ship the new Remote.com, there are a few tips and tricks we're happy to share.

Engineering