DEV Community: Kadi Kraman

10 Tips for Structuring a React Native Project

Kadi Kraman — Sun, 29 Nov 2020 12:25:03 +0000

When starting a new project, there are plenty of choices to be made around code style, language, folder layout, and more. Consistency is the key for creating clean, maintainable codebases. Therefore once decided, you'd usually need to stick with these choices for a while.

Time and experience will teach you what works and what doesn't. But what if you don't have time? You can always use someone else's experience.

Here are my top 10 tips for structuring a React Native project:

1. Use TypeScript

Yes, there is a bit of a learning curve if you're used to plain JavaScript.

Yes, it's worth it.

Typed JavaScript makes refactoring a whole lot easier, and when done right, gives you a lot more confidence in your code. Use the guide in the docs for setup instructions. Make sure to enable strict mode ("strict": true in the compilerOptions).

You can also add type checking in your CI with tsc --noEmit, so you can be confident in your types!

2. Set up a module alias to `/src`

Set up a single module alias to /src (and a separate one for /assets if needed), so instead of:

import CustomButton from '../../../components/CustomButton';

you can do:

import CustomButton from '@src/components/CustomButton';

I always use a @ or a ~ in front of src to highlight it's an alias.

I've seen implementations where folks set up multiple type aliases - one for @components, one for @screens, one for @util etc, but I've found a single top level alias to be the clearest.

There's a handy guide for setting this up with TypeScript in the React Native docs.

3. Use Inline Styles

You have an option for using the built in inline styles, or Styled Components.

I started off with Styled Components, then switched to inline styles, because there used to be a performance implication, though that's negligible, so now it's just a preference.

4. One Style File Per Component

Each component should have their own style file with a styles.ts extension:

FirstComponent.tsx
FirstComponent.styles.ts
SecondComponent.tsx
SecondComponent.styles.tsx

Note, the .styles.ts in the filename is just a convention I use to indicate that the styles belong to the component, the TypeScript compiler will treat these as regular .ts files.

Each style file exports a single style object for the component:

// FirstComponent.styles.ts

import { StyleSheet } from 'react-native';

const styles = StyleSheet.create({
  container: {
    padding: 20,
  },
});

export default styles;

Each component only imports only its own styles:

// FirstComponent.tsx

import styles from './FirstComponent.styles';

...

5. Use Global Styles

Create a globalStyles.ts file at the top level of the /src directory, and import it to the .styles.ts as needed.

Always use constants for:

colours
fonts
font sizes
spacing

It may seem tedious at first, but handy in the long term. And if you find you're ending up creating constant for every single space, it's something to gently bring up with the Design team, as design guides would generally not want that.

6. Flatten Style Constants

Instead of:

const globalStyles = {
  color: {
    blue: '#235789',
    red: '#C1292E',
    yellow: '#F1D302',
  },
};

Do this:

const globalStyles = {
  colorBlue: '#235789',
  colorRed: '#C1292E',
  colorYellow: '#F1D302',
};

It can be tempting to group these, but I've found that keeping them flat can be more handy, e.g. if you wanted to replace all instances of colorRed in your codebase, you could do a find and replace, whereas with colors.red it'd be harder, since the colour could have been destructured.

7. Use Numbers in Style Constants

Instead of:

const globalStyles = {
  fontSize: {
    extraSmall: 8,
    small: 12,
    medium: 16,
    large: 18,
    extraLarge: 24,
  },
};

Do this:

const globalStyles = {
  fontSize8: 8,
  fontSize12: 12,
  fontSize16: 16,
  fontSize18: 18,
  fontSize24: 24,
};

The first option may look nicer when writing it down, but during development, you don't tend to care about "medium" and "large", and just care about the number. And it will avoid the awkward naming when the designers inevitably add a font size 14 and you have to start calling your variables things like mediumSmall.

8. One Component Per File

Here's the template for a new component:

import React from 'react';
import { View, Text } from 'react-native';
import styles from './App.styles';

const App = () => {
  return (
    <View style={styles.container}>
      <Text>Hello, world!</Text>
    </View>
  );
};

export default App;

Some things to note here:

function components over class components: I'd always use function components and manage any state and side-effects using hooks
I use constant functions, but both const and function are equally good here. In fact function might be better in the long term
default export: I always use a default export, though there is an argument to be made that named exports are better since they'll be clearer to refactor, and I agree - that might be the next step

9. Separate Components and Screens

Here's a typical folder structure I end up with:

/assets
  /images
    image.png
    anotherImage.png
  /icons
    icon.svg
    anotherIcon.svg
/src
  /components
    Component1.tsx
    Component1.styles.ts
    Component1.test.ts
    Component2.tsx
    Component2.styles.ts
    Component2.test.ts
  /screens
    Screen.tsx
    Screen.styles.ts
    Modal.tsx
    Modal.styles.ts
  App.tsx
  globalStyles.ts
  types.ts

I always separate components in the /components directory and the screens and modals in the /screens directory. When using react-navigation, there is no structural difference between screens and modals, but I prefer to also differentiate the intent by naming the file SomethingModal.tsx.

Another thing to note is the file names - rather than creating a folder with the file name, and naming each file index.tsx, the filename should reflect the component name. That is mostly for convenience - in most editors, it'll get tedious to track down which file you're editing when they're all called index.tsx

I've also seen implementations where all components are imported to a single index.ts file and exported from there. I personally am not a fan of that solution and see it as an unnecessary extra step.

10. Lint Your Code

It's worth it. Trust me!

Use eslint and prettier - they actually come pre-installed when you initialise a new project
Set up a pre-commit hook - I usually set up a pre-commit hook for linting and pre-push hook for tests. There's a great guide here.
Check lint, test and TypeScript errors on CI! This is so important - the only way to ensure a consistent code style across the project lifecycle. Setting up CI is one of the first things I do when starting a new project.

Hope this helps! Got any tips of your own that I did't list here? Let me know in the comments! 👀

An Open Source Maintainer's Guide to Publishing npm Packages

Kadi Kraman — Sat, 23 May 2020 16:34:49 +0000

The JavaScript community is built on Open Source and being able to give back to the community feels most gratifying. However, publishing a package for the first time might feel rather daunting, and publishing a release candidate may be a bit scary even for experienced authors. I hope to give some insight and helpful tips, especially for new authors.

I have owned two open source libraries: a tiny utility library for DraftJS called draftjs-md-converter and a React Native security library called react-native-app-auth. I am certainly not as heavily involved in Open Source as some, but I have had the sole responsibility of publishing new versions of these libraries for several years so I think I have enough experience to justify this blog post! I remember how scary it was to publish a library for the first time, and I still remember how apprehensive I felt publishing a release candidate. The purpose of this writeup is to produce a guide on how to publish packages: both a comprehensive guide for new authors, and a sanity check for future me.

I will cover the following:

Setting up your repo for publishing
Publishing a package (initial release)
Versioning
Publishing a package (subsequent releases)
Publishing alpha / beta / release candidate versions

You can use npm or yarn, it's completely up to you. The publish commands are identical. I will be using npm throughout.

Setting up your repo for publishing

Before you're ready to run the publish command, you should check that your package is in a good state to be published. Here are a few things you might want to consider:

Check the package name

The name field in your package.json will be the name of your published package. So for instance if you name your package package-name, users will import it with

import ... from "package-name";

The name needs to be unique, so make sure you check the name is available on https://www.npmjs.com/ or your publish command will fail.

Set the initial version

The version attribute in your package.json will determine the version of the package when published. For your initial release you might use:

{
  "version": "0.0.1"
}

{
  "version": "1.0.0"
}

NPM packages use semver for versioning, which means the version consists of 3 numbers: the major, minor and patch version. We will talk more about versioning in the "Versioning" section.

Make sure your repository is not private

In the package.json you may have an attribute "private": true. It is a built in protection so you wouldn't accidentally publish something that's meant to be private. It is generally a good practice to use this if you're building something that is not meant to be open source, like a personal or a client project. However if you're about to publish the repo as a package, this line should be removed.

Add a license

Ensure you have set the license in your package.json. This is to let people know how you are permitting them to use your package. The most common licenses are "MIT" and "Apache-2.0". They are both permissive, allowing users to distribute, modify, or otherwise use the software for any purpose. You can read more about the differences here. I have always used the "MIT" license.

Check the entry point

The main field in your package.json defined the main entry file for the package. This is the file the users will access then importing your package. It'll usually be something like ./index.js or ./src/index.js depending on the location of your entry file.

Restrict the files you want to publish

Be default, publishing a package will publish everything in the directory. Sometimes you might not want to do that, e.g. if your repository includes an example folder or if you have a build step and only want to publish the built bundle. For that purpose, there is a files field in the package.json. If omitted, the field defaults to ["*"], but when set, it includes only the files and directories listed in the array. Note that certain files are always included, even if not listed: package.json, README, CHANGES / CHANGELOG / HISTORY, LICENSE / LICENCE, NOTICE, and the file in the "main" field.

Add a build step

Sometimes, you may need a build step. For example if you've written your package using Flow, TypeScript or cutting edge JavaScript features that aren't implemented in all browsers, and want to compile/transpile your package to vanilla JavaScript that anyone could use. For this you can use a prepublish script like so:

{
  "scripts": {
    "prepublish": "npm run your-build-script"
  }
}

This will be run automatically when you run the publish command. For example in this package I use the prepublish script to rebuild the app in the dist directory. Notice also that the main field in this package.json is set to "main": "dist/index.js" since I want the users to access the built file.

There are more built in scripts for various occasions, but this is the only one I've had to use when publishing packages. You can read more about other available scripts here.

Publishing a package (initial release)

Clone your repo, and make sure you're on the latest master branch (or whatever your main branch is) with no uncommitted changes.

Create an account on https://www.npmjs.com/ if you don't have one already, and use these credentials to log in on your terminal:

npm login

Finally, in your project repo, run:

npm publish

If you've set up two factor authentication, you'll get a prompt for it in your terminal before the publish is completed. Once the command has finished successfully, you should be able to instantly see your package at https://www.npmjs.com/package/package-name where package-name is the name of your package set in the package.json, and people will be able to install your package with:

npm install package-name

Versioning

Publishing subsequent versions of the package involves more thought, because now we need to consider versioning. As mentioned above, npm packages are versioned using semver. This means that there are 3 types of releases: major, minor and patch, and you should use these to communicate the types of changes in your library.

Major changes include anything that is incompatible with the previous versions
Minor changes are usually new features and bigger bug fixes
Patch changes are tiny bug fixes or additive changes

One thing to note is that the semver naming is a bit misleading, specifically in "major" - a major release doesn't necessarily mean that a lot has changed. It means that when going from the previous to current version, there is a breaking change, and that the users of your library might need to change something in their code in order to accommodate the latest version. For instance, changing an exported function name or parameter order would be considered major changes. A lot of maintainers tend to collect breaking changes and release them all together to minimise how often the major version is incremented.

The reason you should only do breaking changes in major releases is because the users of your library may opt in to all future patch and minor versions silently, so the next time they run npm install you might end up breaking their build.

In the package.json, this is communicated with ~ and ^ where ~ opts in for all future patch releases and ^ opts in for all future patch and minor releases:

~1.2.3 will match all 1.2.x versions but will miss 1.3.0

^1.2.3 will match any 1.x.x release including 1.3.0, but will hold off on 2.0.0.

Side note: when the major version is 0, the package is considered unstable and so the ^ acts the same as ~ and for all releases before major 1 you may publish breaking changes in minor releases.

There is no option to opt in for all future major releases, because they are expected to be breaking and thus should be manual upgrades. Source.

Publishing a package (subsequent releases)

This is how you do releases after the initial one. As before, you should ensure you're on the master branch with no uncommitted changes. Consider what type of release this is: major, minor or patch. Now run the command to increment the version in your working directory, using major, minor or patch depending on the type of the change:

npm version minor

This is a convenience method that does a couple of things:

increments the version in your package.json based on the type of the change
commits this version bump
creates a tag for the current release in your .git repo

Now all that's left to do is to run the publish command as before:

npm publish

It is important to make sure you do the version bump before the publish. If you try to publish the same version of the library twice, the command will fail.

Finally, you'll want to push the version bump commit and the tag:

git push
git push --tags

Notice that you'll have to push the tags separately using the --tags flag.

If you're using GitHub to host your repository, the tags will show up under the Releases tab on your repository, e.g. https://github.com/kadikraman/draftjs-md-converter/releases

It is good practice to write some release notes against the tag. I usually also use this space to thank any contributors!

Publishing an alpha / beta / release candidate

An alpha / beta / release candidate is usually an early access version of a major release. When you're about to do a major change, you might want to give your users a chance to try out the new release first on an opt-in basis but with the expectation that it may be unstable.

Basically what we want to achieve is to publish a new version "silently" that would allow only interested users to opt in for.

Let's look at how you might create a release candidate. Suppose you are currently on v3.4.5 and you want to do a release candidate for v4.

First, we increment the version. The npm version command allows you to provide your own version number. In this case we're going to say it's the first release candidate for v4:

npm version 4.0.0-rc1

As before, this does the version bump, commits the change, and creates the tag. Now to publish the package. This is the most important step, since you want to ensure none of your users get this release candidate version by default.

The publish command has a --tag argument, which defaults to "latest". This means that whenever someone npm installs your library, they get the last publish that has the "latest" tag. So all we need to do is provide a different tag. This can be anything really, I have usually used "next".

npm publish --tag next

This will publish your package under the next tag, so the users who do npm install package-name will still get v3.4.5, but users who install npm install package-name@next or npm install package-name@4.0.0-rc1 will get your release candidate. Note that if you publish another release candidate with the "next" tag, anyone installing npm install package-name@next will get the latest version.

When you're ready to do the next major release, you can run npm version major (this will bump the version to 4.0.0) and npm publish as normal.

Conclusion

That's pretty much it! Publishing packages can be a bit scary the first few times, but like anything it gets easier the more you do it.

Thank you for contributing to Open Source!

Building an Animated Drawer in React Native

Kadi Kraman — Fri, 01 May 2020 21:17:26 +0000

Animations are a sure way to improve user experience and delight in your app. However, they are often not that straightforward to implement, and so end up as a "nice to have" at the very bottom of the backlog.

React Native actually comes with some rather handy features that make adding certain types of animations a lot more straightforward than you might imagine!

In this tutorial, I will show you how to create an animated drawer component in React Native - without using the Animated API!

LayoutAnimation

The key to building this is LayoutAnimation. It is a built in feature that automagically animates views to the new position when a layout change happens.

Let's demonstrate how this works by animating a box to grow and shrink onPress.

First let's create a box:

import React from "react";
import { View, SafeAreaView, StyleSheet } from "react-native";

const App = () => {
  return (
    <SafeAreaView style={styles.safeArea}>
      <View style={styles.container}>
        <View style={styles.box} />
      </View>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  safeArea: {
    flex: 1
  },
  container: {
    justifyContent: "center",
    alignItems: "center",
    flex: 1
  },
  box: {
    backgroundColor: "pink",
    height: 50,
    width: 50
  }
});

export default App;

Now let's update out code so that the box toggles from being 50x50 to 200x200 in size when you tap on it.

use the useState hook to hold the state for whether the box is expanded
update the box style so that it is 200x200 when isExpanded is true
add a Touchable around the box and toggle expanded state onPress

-import React from "react";
+import React, { useState, useCallback } from "react";
-import { View, SafeAreaView, StyleSheet } from "react-native";
+import { View, SafeAreaView, StyleSheet, TouchableOpacity } from "react-native";

const App = () => {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const handlePress = useCallback(() => {
+    setIsExpanded(val => !val);
+  }, []);
  return (
    <SafeAreaView style={styles.safeArea}>
      <View style={styles.container}>
+        <TouchableOpacity onPress={handlePress}>
-          <View style={styles.box} />
+          <View style={[styles.box, isExpanded ? styles.expanded : undefined]} />
+        </TouchableOpacity>
      </View>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  safeArea: {
    flex: 1
  },
  container: {
    justifyContent: "center",
    alignItems: "center",
    flex: 1
  },
  box: {
    backgroundColor: "pink",
    height: 50,
    width: 50
-  }
+  },
+  expanded: {
+    height: 200,
+    width: 200
+  }
});

export default App;

Now the box toggles from being 50x50 to 200x200, but there's no animation. This is where LayoutAnimation comes to play. We want to tell the layout that the next time there is a UI change, instead of snapping to it, animate.

import React, { useState, useCallback } from "react";
-import { View, SafeAreaView, StyleSheet, TouchableOpacity } from "react-native";
+import { View, SafeAreaView, StyleSheet, TouchableOpacity, LayoutAnimation } from "react-native";

const App = () => {
  const [isExpanded, setIsExpanded] = useState(false);
  const handlePress = useCallback(() => {
    setIsExpanded(val => !val);
+    LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
  }, []);
  return (
    <SafeAreaView style={styles.safeArea}>
      <View style={styles.container}>
        <TouchableOpacity onPress={handlePress}>
          <View style={[styles.box, isExpanded ? styles.expanded : undefined]} />
        </TouchableOpacity>
      </View>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  safeArea: {
    flex: 1
  },
  container: {
    justifyContent: "center",
    alignItems: "center",
    flex: 1
  },
  box: {
    backgroundColor: "pink",
    height: 50,
    width: 50
  },
  expanded: {
    height: 200,
    width: 200
  }
});

export default App;

Note that if you need this to work on Android as well, you'll need to place this extra it of code just under your import statements:

import { UIManager, Platform } from "react-native";

if (Platform.OS === "android") {
  if (UIManager.setLayoutAnimationEnabledExperimental) {
    UIManager.setLayoutAnimationEnabledExperimental(true);
  }
}

That's literally it! Sure, there are limits to what you can achieve with this, but there is quite a bit you can use LayoutAnimation for with very little additional developer effort.

Check out the source code for the animated box here

Building an animated drawer

Now that you have the power of LayoutAnimation in your back pocket, you can use this to build a drawer.

Let's see how to build a single drawer. The core concept is this:

create a touchable area which is the always visible title
add a list of elements underneath it that should be displayed when the drawer is open
wrap the list of element in a view and give it a conditional style that sets the view height to 0 when the list is "closed"
call LayoutAnimation.configureNext immediately after triggering the state change to open or close the drawer.

The code for a single section should look like this:

import React, { useState, useCallback } from "react";
import {
  View,
  Text,
  FlatList,
  LayoutAnimation,
  TouchableOpacity,
  UIManager,
  Platform
} from "react-native";

if (Platform.OS === "android") {
  if (UIManager.setLayoutAnimationEnabledExperimental) {
    UIManager.setLayoutAnimationEnabledExperimental(true);
  }
}

const Section = () => {
  const [isOpen, setIsOpen] = useState(false);

  const toggleOpen = useCallback(() => {
    setIsOpen(value => !value);
    LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
  }, []);

  return (
    <>
      <TouchableOpacity onPress={toggleOpen}>
        <Text>Section header</Text>
      </TouchableOpacity>
      <View style={!isOpen ? { height: 0 } : undefined}>
        <FlatList
          data={["Item 1", "Item 2", "Item 3", "Item 4"]}
          keyExtractor={item => item}
          renderItem={({ item }) => (
            <View style={styles.item}>
              <Text>{item}</Text>
            </View>
          )}
        />
      </View>
    </>
  );
};

export default Section;

Now all that's left to do is add some styling and a couple more sections and you're all done! Check out the source code for the animated drawer here

I would also recommend reading up on LayoutAnimation to learn more about ways you can customise it.

Layout Animation in the Wild

Here is an example of a feature in a production app that I built using LayoutAnimation. The drawer here is built using exactly the method described in this article!