Technology

Kristina Vragovic

Bringing Rails Convention to the Wild West of JS

Aug. 22, 2018

Necessity is the mother of invention — but Rails is the mother of convention. And sometimes, what you really need is some structure.

Here at 20spokes, we have branched into mobile in a big way, using React Native with Rails APIs. As a consultancy, we have the unique perspective of building projects from scratch often, and we kept coming back to folder structure. Namely, how on earth does anyone find anything in a React Native (or React.js) app as it grows?

Most of the React tutorials we saw out there had three main folders for their files: elements, modules, and components. (Redux projects will sometimes expand that to include an actions folder.) But try getting someone to actually define what an element is, versus a module, versus a component, and the argument quickly becomes circular. Elements are reusable, they say. Well, so are modules. Modules are bigger, though. Sort of.

So we decided to write our own rulebook. Trash it if you like, but it’s worked pretty well for us so far, and going back to maintain projects we built before we established this style? The difference is mind-boggling.


    |_ __tests__
      |_ ...mirrors the src folder
    |_ android
    |_ assets
    |_ ios
    |_ src
      |_ actions
      |_ contexts
        |_ Profile
          |_ modules
            |_ AvatarUploader.js
          |_ views
            |_ EditProfileView.js
            |_ PublicProfileView.js
          ProfileStyles.js
      |_ elements
        |_ Buttons
          |_ ButtonPrimary.js
          |_ ButtonSecondary.js
      |_ helpers
      |_ layouts
      |_ navigators
      |_ utils
    App.js
    index.js

Along with this folder structure, we’ve employed babel-plugin-module-resolver to help with the dreaded strings of ../../../../ before import statements. That way, every time we need a common element in a view within the contexts folder, the import path can be as simple as elements/Buttons/ButtonPrimary.js. Learn more about that plugin here — it’s been key to our success with this structure.

Putting it into contexts

If you’re building any kind of mildly robust mobile application that makes requests to an API, you probably have several "flows" through the app. Settings. Login. Feed. Profile. Onboarding. Any "section" of the app that you’ve probably already chunked out as a feature set is probably also a context. We decided to create a folder for each of these contexts, with all the views in that context along with all of the modules/elements that are particular to that context. [1]

For example, a public profile view, an editable profile view, and an avatar uploading module would all be in a Profile context folder. If an element is reusable outside of that component, stick it in the elements folder instead. The contexts folder was the real heavy-hitter in our redesign. You’re welcome.

Let me lay it out for you

Most of the apps we create have custom navigation bars/drawers or SafeArea wrappers that need to go on every page. We usually call this a ViewWrap.js or TopNav.js, whatever the use case is. Sometimes different kinds of views have different view wraps. The layouts folder is for these — just like in Rails.

Check the GPS

The navigators folder is a handy place for all your navigation-related files.

If you’re familiar with navigation libraries for react like React Navigation, you know that each app "flow" needs a navigator file or something like it. We used to keep these in the junk pile, AKA the top level of the folder structure along with App.js and index.js. But for complex apps with lots of form flows, or different user journeys, having a navigators folder — with subfolders like Admin or Onboarding or other, more specific navigational needs — makes it a lot easier to grok the app’s navigational complexities.

Going off the Rails

As a software consultancy, we have a particular interest in making sure that our code is easy to read and maintain by another team sometime down the line. But let’s be honest — we’ve all read a codebase that we wish had been written with future developers in mind.

Going back to old projects, ones built before we adopted this new folder structure, isn’t a total nightmare (we have always been pretty good at this readability stuff, after all). But it truly is amazing how much of a difference the new structure has made. No longer do I have to wonder which Events folder is going to have EventCard.js in it — src/elements/EventCard.js or src/modules/EventCard.js? There’s only one Events folder, src/contexts/Events. Something reusable like a card will maybe be another folder deep, in a modules folder particular to events. But that’s it. No more digging!

Even if you decide not to implement our folder structure for your next React or React Native project, what I hope you’ll take away from this success story is that it’s invaluable to consider lessons you’ve learned from other frameworks. What makes Rails infinitely easy to jump into and know where to look for things is totally doable in React. So get after it!

[1] We did not know that React 16.4.2 was about to come out with this Context thing. Sorry for any confusion. Call the contexts folder whatever you want?

Kristina Vragovic

What People Are Reading

Technology

11/20/17

Cross-Platform mobile development is cost-effective and faster to launch

Two years ago, if a person approached us for mobile app development, the first question would be what platform to launch on first - iOS or Android. It was almost double the cost to deploy on both and double the maintenance.

Fast forward to today, we can deploy on iOS and Android quicker before, at the same time, and with the expected native quality.

So what has changed? Technology has gotten a lot better. We particularly use React Native, an open source framework from Facebook, that allows developers to develop in a common language, Javascript, and deploy on both iOS and Android.

And it is native! Previous technologies for cross platform mobile apps would create a wrapper of a web view. Think of the older experience as using the browser on your phone for a site with a few more bells and whistles. It was close but the difference is noticeable when switching to native applications, from scrolling to the overall experience.

How does this impact everything now?

Cost is no longer double for both platforms. It can even cost less due to wide spread community support developing open source libraries.

Maintenance is a lot easier. A majority of the issues can be fixed in one code base and of the same language.

Recruitment and team knowledge is easier. Your team only need to know one language and most developers know Javascript. iOS is written in Objective C or Swift and Android is written in Java.

Reusable code for desktop web views. With React Native, we are able to share over 50% of the code with the web view, saving all of the above even more.

Stay tuned, as I’ll be going more into the technologies and other benefits.

News

10/18/17

ChangeMaker Launches!

In a world where marches and protests are making weekly headlines, people are always looking for the next cause to get behind.

But what do you do when a cause or issue you’re passionate about needs more awareness and support? How do you find people to come together? How do you organize people, activities, events, and whatever else you might need to do? And if you do find people, how do you manage all the different moving parts?

And, well, what does that have to do with us at 20spokes?

Meet ChangeMaker -- a project we recently completed and launched.

Similar to sites like Kickstarter or Indiegogo, ChangeMaker allows organizations to add a project and find fellow activists to donate to or join the cause as a volunteer. The interface provides organizations the ability to detail an issue or problem, outline a solution, and how donors or volunteers can help. When people join the project as a volunteer, they can specify their particular skillset in fields such as marketing, design, legal, or data so project managers can delegate tasks to the right people.

With funding from donations, users can work on projects for their cause by using the free website. While most project management tools have some sort of fancy, pay-to-use features, ChangeMaker is completely free to use because it is donor funded and donor maintained.

We branded, designed, and coded the ChangeMaker platform in a Rails environment. We also integrated Stripe Connect, which enables organizations to receive those donations they need to power their projects.

Putting all this together sounds like it would take a good chunk of time, right? But we kicked off this project on August 8 and launched the website this week. A little more than two months. Not too shabby, eh? Just in time for the Newfounders Conference. ChangeMaker will have a big presence at the conference with donors ready to help out organizations that have ready-to-pitch projects for its demo night. Nothing is too small or too large for ChangeMaker to help its users and organizations tackle.

Give ChangeMaker a whirl at changemaker.newfounders.us.

Technology

1/6/17

React Lessons for Newcomers

At 20spokes, developers spend a roughly equal amount of time between Ruby on Rails and React. While we enjoy working in both frameworks, they are quite different in approach, and going from a Rails way of thinking to a React way of thinking can be an adjustment.

One major way in which these frameworks are different is that Rails takes care of a lot of architectural issues that React leaves open for interpretation. Coming from a Rails background, I found the openness of React to be a bit anxiety-inducing at first, but I've come to really embrace it, because it's forced me to think more carefully than ever about how other developers would approach my code.

As a team, we've also considered what our best practices should be towards React, as we all want to make our code understandable and friendly to anyone who encounters it. To that end, below is a (growing) list of our approaches to making our React projects not only maintainable, but enjoyable to work with.

Be relentless with components

The basic building block of React is the component. To those new to React, they can best be thought of as modules.

As a developer, I start to get nervous when I see large components that perform various functions. The solution to keeping your files short and sweet is to take every opportunity to break your objects into re-useable components. Having larger components may not seem like a big deal when starting a project from scratch, but if you relentlessly component-ize you'll thank yourself as your project grows.

There are some code smells to recognize when you should create new components. If you see lots of groups of markup within a single div, those groups should probably be their own component.

If we have lots of renderXXX functions within in one component that render more markup, that's usually a code-smell that whatever is being returned from those functions should be their own component.

Make components as reusable as possible by passing dynamic data as props.

Privilege functional components over class-based ones

In many cases, it's overkill to Use React's Component class for every component you create. Not all components need access to the Lifecycle Methods or local state that Component provides. Start with stateless functional components and turn them into React Component instances as needed.

Take advantage of PropTypes

We started the practice of listing out PropTypes at the bottom of every component, so other developers can quickly reference what props are needed or optional. Oftentimes, we'd investigate what data we should expect in a component by looking up examples of that component elsewhere in the codebase. This easily can be avoided by using PropTypes, which provide a quick way to see what data is being passed, and of what type that data should be. Here's an example from our reusable Button component:

Button.propTypes = {  
  text: PropTypes.string.isRequired,
  onPress: PropTypes.func.isRequired,
  disabled: PropTypes.bool,
  icon: PropTypes.string,
}

We're pointing this out because, while Facebook already notes it as a best practice in their documentation, it's something that's easy to skip over or forget to do. But for something that's not hard to do at all, it provides a lot of value when developing and maintaining your app.

Use Lifecycle Methods with care

Despite being incredibly powerful, lifecycle methods (like ComponentDidUpdate) can cause a lot of headaches to those new to React. Be careful when updating state or props within these methods, as it may cause infinite looping.

For this reason, I prefer to place lifecycle methods at the very top of a component declaration, so I can see all of that logic together when debugging.

Check out part 2 of this series, Redux Lessons for Newcomers.