Forem: Arnel Enero

Pitfalls of `process.env` every React developer should know

Arnel Enero — Wed, 14 Sep 2022 08:32:37 +0000

Pitfall #1: It does not exist in the browser

Unlike in Node.js, there is no such thing as process.env object in the browser. One neat webpack trick, however, allows us to "emulate" this construct right in our React app.

Webpack's DefinePlugin injects environment variables by token replacement of process.env.SOME_ENV_VAR. The final compiled JS will not have any reference to process.env because, remember, it does not exist in the browser. So if we have something like this:

console.log(process.env.SOME_ENV_VAR);

webpack will compile that to something like this:

console.log('value of SOME_ENV_VAR');

Pitfall #2: We cannot assign values to it in React code

This one is really just a natural side-effect of pitfall #1. Since process.env will not exist in the compiled JS code, it follows that it doesn't make sense to try overriding environment variables inside our React app like this:

process.env.REACT_APP_ENV_VAR = 'cannot do this';

Pitfall #3: It may get compiled in a way you didn't expect

There is one significant pitfall that we need to be wary of: We need to make sure that all environment variables referenced in our source code are defined in our .env files or elsewhere.

If DefinePlugin cannot find a referenced env var's value, it will not token-replace any references with undefined. For example, if we have not defined REACT_APP_NOT_FOUND anywhere, but we have this code:

console.log(process.env.REACT_APP_NOT_FOUND);

will not translate to this:

console.log(undefined);

Instead, webpack will string-replace just the process.env part of the token with the entire key-value mapping of env vars. So the translation is actually something like this (even after minification):

console.log(
  {
    NODE_ENV: ‘development’,
    REACT_APP_NAME: ‘My App’,
    REACT_APP_ID: ‘232809283923’,

    // ... possibly a long list of other values
  }.REACT_APP_NOT_FOUND
);

Now imagine if we have lots of checks like this throughout our code:

if (process.env.REACT_APP_SOME_OPTIONAL_FLAG) { 
  /* . . . */ 
}

and we only define env vars in our .env file for flags that are true, thinking it’s fine because the logic above only cares about the existence of the flag, not its value.

But take the above compiled code containing the entire env vars object literal, and multiply it by who knows how many possibly-undefined env vars... for sure it’s going to hurt our bundle size.

NOTE: The above behavior is based on how process.env is typically configured with DefinePlugin, such as in Create React App. YMMV.

Why explicit return type is a good thing

Arnel Enero — Tue, 06 Sep 2022 07:06:48 +0000

Back when I was just starting with TypeScript, I used to neglect the value of declaring an explicit return type for my functions. Why bother specifying it when there is type inference and IntelliSense, right? Well, I was very wrong.

Turns out that its main benefit is actually not to whomever might call my function, but rather to whomever might edit my function in the future. Here's why...

Imagine I have this function:

function getAge(person: Person) {
  return calculateAge(person.birthdate);
}

This is all good, as obviously it returns a number, and IntelliSense tells me that, too. But then later on, someone edits my function to add a guard condition as follows:

function getAge(person: Person) {
  if (person.birthdate === undefined) return null;

  return calculateAge(person.birthdate);
}

This won't trigger a TS error at this function, but now the inferred return type has become number | null, which is clearly different from the original intention. Now we have introduced, possibly unintentionally, a breaking change.

Now imagine if I have specified a return type in the first place, as follows:

function getAge(person: Person): number {
  // . . .
}

then my team mate would have known from the start what can and can't be changed in the implementation without making a breaking change.

JS Tidbit: A neat trick to compose arrays with conditional items using filter(Boolean)

Arnel Enero — Sun, 31 Jul 2022 00:19:00 +0000

Just a quick tip that you might find useful with JavaScript...

When composing an array, we sometimes need to deal with items that are either:

potentially null or undefined, in which case we don't want to include it; or
should only be included if a certain condition is satisfied

Here's a neat trick to do that cleanly:

const list = [
  'A',
  somethingThatCanBeNullOrUndefined,
  condition && 'B'
].filter(Boolean);

In the above example, .filter(Boolean) will pass each array item to the Boolean() constructor, which converts it to a boolean value (using JavaScript's truthy/falsy coercion).

Therefore, if somethingThatCanBeNullOrUndefined is null or undefined it becomes false and hence excluded by the filter. Similarly, if condition && 'B' short-circuits to false the item 'B' is excluded.

Turn a single brand color into your own Complete Web Color System... in minutes!

Arnel Enero — Sun, 20 Mar 2022 22:03:36 +0000

How many times have you neglected your app's UI just because you had a deadline, and you needed to focus on your app's functionality instead?

Color forms an important foundation of every UI. It enables consistent expression of your brand/identity and style, and effective communication of intent and meaning.

However, it can be quite daunting for developers like you and me to implement a proper color system, especially when this task has to contend with working on actual functionality of our app.

For Web developers, here's where Simpler Color could help. I wrote this small library so that we no longer have to sacrifice not having a cohesive, professional UI color system while focusing on the other important stuff.

And all you need is a single brand color...

Easy as 1-2-3

Step 1: Install simpler-color

npm install simpler-color

Step 2: Specify your brand color, and it generates the rest of the base colors!

import { harmony } from 'simpler-color'

// Generate 5 harmonious base colors from your main brand color!
const baseColors = harmony('#609E3F')

(You can also define your own custom base colors if you prefer, or if you already have a set of brand colors)

Step 3: Create your color scheme(s) by mapping UI roles to specific colors from the auto-generated palettes

import { colorScheme } from 'simpler-color'

const scheme = colorScheme(
  baseColors, // 👈 From these base colors...
  // 👇 ...your color palettes are auto-generated
  colors => ({
    // 👇 which you then map to UI roles.
    primaryButton: colors.primary(40),
    primaryButtonText: colors.primary(95),
    surface: colors.neutral(98),
    text: colors.neutral(10),
    ...etc,
  }),
)
// Access various UI colors as `scheme.primaryButton` and so on.

Here's the complete range of colors that our example code generates from a single color value of #609E3F:

It's that simple! (Plus the library can do quite a bit more.)

So why don't you give Simpler Color a try. Check it out on GitHub: https://github.com/arnelenero/simpler-color

Please don't forget to give it a star ⭐️ on GitHub if you like the library, its concept and the simplicity.

If some terms used above sound a bit alien to you, check out the comprehensive README in the link above for more details.

Hope you find this library useful. With proper color, even an early prototype or proof-of-concept app would certainly impress!

Learn Navigator 2.0 by Building a Simpler API !

Arnel Enero — Mon, 31 May 2021 14:06:03 +0000

If you are reading this you probably have an opinion about Flutter's Navigator 2.0 being either:

Too complicated, making it difficult to comprehend
Too verbose, requiring a lot of boilerplate to do the job

But despite this, it offers quite a number of features that were not possible with the simpler 1.0.

Well, there's probably no better way to finally decipher Navigator 2.0 than to write our own simple wrapper API on top of the beast. And we'll be solving 2 problems in one go!

Don't worry, we will try to make sense of the whole thing, piece by piece, starting from the general concept down to the nitty gritty, and will be presented in the simplest way possible.

So if you have some time, join me in this exciting challenge. First up, let's give our library a name: ➡️ Flipbook ⬅️.

But hasn't the Flutter team already written a lengthy article explaining 2.0? Yes, but I promise you we can do simpler than that approach. 🤓

Note on 1.0: If you have been writing Flutter apps for some time now, most likely you've already used the original Navigator 1.0. There are tons of materials on 1.0 online, so I won't waste your time on reviewing it here.

What Navigator 2.0 is for

Let's forget about the whole thing about 2.0 being declarative vs. imperative first. If it didn't make it any simpler (many say it got much more complicated) then there is no point in talking too much about this aspect.

Nav 2.0 works in a reactive kind of way, much like how Flutter widgets work. So let's focus on 3 major things that 2.0 tries to achieve here:

Have the navigation react to the app state.
Have the URL update with the app state.
Have the app state react to URL changes.

As you can see above, 2.0 syncs up the navigation with the app state. And with Web now a first-class citizen in Flutter world, there is increased demand to sync the URL with the app, too.

We'll dive into each one of those 3 areas as we look at how Nav 2.0 achieves those goals, and as we build out our simple API.

What our API should look like

Let's ideate a little bit on how we want our Flipbook API to look from developer experience perspective.

A drop-in replacement for MaterialApp could be a good entry point because it immediately feels familiar. So here's a look at an example build method of a top-level App widget:

  @override
  Widget build(BuildContext context) {
    return Flipbook(
      title: config.appName,
      routes: {
        '/login': (context) => LoginScreen(),
        '*': (context) => Shell(),
      },
    ),
  }

Flipbook plays the role of a router. The routes are matched by path, and are enumerated by top-to-bottom priority, with the last one typically being a wildcard to indicate "default" fallback.

To switch screens, we just need to update the navigator state as follows:

  context.route.setState('/login');

Although this looks similar to the pushNamed() approach from 1.0, here we no longer need to worry about calling push, pop or replace. We just set the nav state to the correct path, and Flipbook should do the rest.

Now that we have laid out the basic concept for our API, let's start building...

Linking navigation to app state

The main enabler for this functionality is the router delegate, which is the mediator of all the pieces of our router (the Flipbook widget). The RouterDelegate class is the core of what Navigator 2.0 is all about, so let's carefully dissect this down to the essential pieces.

We'll start by creating our subclass of the router delegate:

class FlippinRouterDelegate extends RouterDelegate<RoutePath>
    with ChangeNotifier { 

  final RouteMap routes;
  final RouteState routeState = RouteState.instance;
  final GlobalKey<NavigatorState> navigatorKey;

  FlippinRouterDelegate(this.routes)
      : navigatorKey = GlobalKey<NavigatorState>() {
    routeState.addListener(notifyListeners);
  }
}

So we can observe above that:

The delegate has a routes property which is the map of routes that we specify when we instantiate Flipbook.
It has a routeState property that stores the current route.
It listens to changes in the routeState.
It is also a ChangeNotifier, so it can also relay the changes that it detects in routeState.
The router delegate uses a generic type <RoutePath> to indicate the data model it uses to represent route URLs internally. Since we like simplicity, here RoutePath is just a type alias for String.

The router delegate is responsible for building the navigator, which controls the switching of our UI screens. So inside our delegate class, let's add this build method:

  @override
  Widget build(BuildContext context) {
    return Navigator(
      key: navigatorKey,
      pages: _getPages(),
      onPopPage: (route, result) => route.didPop(result),
    );
  }

Let's focus our attention on the pages property for a bit. This is a list of pages which represents the navigation history "stack". Initially the default screen is the only value in this list, then as you open screens on top of the last one (stack vs. replace), the additional screens are appended to the pages list.

So let's say you have a MainScreen and from there you navigate to a DetailScreen that opens on top of it, the pages stack will look like this:

      pages: [
        MaterialPage(
          key: ValueKey('/main'),
          child: Builder(
            builder: (context) => MainScreen(),
          ),
        ),
        MaterialPage(
          key: ValueKey('/detail'),
          child: Builder(
            builder: (context) => DetailScreen(),
          ),
        ),
      ],

Our _getPages() method will be responsible for dynamically generating this list based on the valid routes we specified when we instantiated Flipbook, and the Navigator's state.

Let's add our implementation of _getPages(). Remember we're still on our router delegate class.

  PageList _getPages() {
    PageList pages = [];

    for (String key in routes.keys) {
      if (_matchesRoutePath(key) || key == '*') {
        pages.add(FadeAnimationPage(
          key: ValueKey(routeState.path),
          child: Builder(
            builder: routes[key]!,
          ),
        ));
        break;
      }
    }
    return pages;
  }

The _matchesRoutePath() function checks if the current route path matches one of those listed in the delegate's routes property. I'll leave the implementation of this function to you, as it is pretty much an exercise of logic, rather than Nav 2.0.

So we've covered the navigation part, and our router delegate class is almost complete. Let's set it aside for a while and take care of the other important piece.

At the other end of the link we're connecting is the part of the app state that, when updated, will trigger a navigation. Let's refer to this as the route state.

Let's define our RouteState class:

class RouteState extends ChangeNotifier {
  String _path = '';
  PathParams _params = const {};

  String get path => _path;
  Map<String, String>? get params => _params;

  void setState(String newPath, [PathParams newParams = const {}]) {
    if (_path == newPath) return;

    _path = newPath;
    _params = newParams;
    notifyListeners();
  }

  static final RouteState instance = RouteState();
}

Notice that:

The RouteState is also a ChangeNotifier, so that the router delegate can listen to it.
It has a path property which stores the current URL of the current route
It also has a params property which is a map of URL parameters (if any). For example, if the route path looks something like /items/:id, and the matched URL is /items/1234, then our map will look like this: {'id': '1234'}.
Changes to these properties must be done by calling setState() which notifies listeners of all such changes.

With that we've completed the connection between our navigator and the app state. Up next, we'll link up the app state to the route URL...

Updating the URL when app state changes

Although unnecessary most of the time, Nav 2.0 provides flexibility to "translate" URLs into a format that your app can use internally, sort of like a serialize/deserialize thing. It allows us to extend a RouterInformationParser class for this purpose. (What a long name, I know! 😂)

But for us who prefer simple solutions, let's just keep the URLs as plain strings, so here's our implementation of the parser:

typedef RoutePath = String;

class RouteParser extends RouteInformationParser<RoutePath> {
  @override
  Future<RoutePath> parseRouteInformation(
      RouteInformation routeInformation) async {
    return routeInformation.location ?? '/';
  }

  @override
  RouteInformation restoreRouteInformation(RoutePath data) {
    return RouteInformation(location: data);
  }
}

It's just the same string value through and through. Nothing to see here.

Now let's enable auto-updating our URL on every change to the pertinent app state (i.e. the RouteState). Again it's our route delegate that will mediate the whole process. Here are the steps:

listen for state change (✅ we already implemented this).
Router delegate notifies our router (yes, Flipbook) that the URL needs updating, then the router picks up the active route path from the delegate.
The router uses the parser's restoreRouteInformation to rewrap the URL in "route information" format. (✅ already covered above)

So what's still missing is the piece that handles that second step. Because we chose to use good ol' string format for route path, it's actually as simple as adding one line (a getter) to our FlippinRouteDelegate class:

  RoutePath get currentConfiguration => routeState.path;

This one is called by the router (Flipbook) to fetch the route path from the delegate.

Now the inverse of this process: let's enable RouteState to change whenever the URL changes (e.g. for Flutter Web, when user manually types a deep-linking URL)...

Updating the app state when the URL changes

This time here's what's happening:

The URL (manually) changes
The router/Flipbook uses the parser's parseRouteInformation to translate the URL info.
The router calls a method in the delegate to inform of this update. (👈 This is what we still need to add to our delegate class).

The method we're talking about is the setNewRoutePath(). Let's add that to our FlippinRouterDelegate:

  @override
  Future<void> setNewRoutePath(RoutePath path) async {
    routeState.setState(path, _getParams(path));
  }

We're done linking the URL to the app state. And with that, our FlippinRouterDelegate implementation is now complete! Time to finally assemble our Flipbook router widget...

Putting it all together

If you're still with me, kudos for the patience and enthusiasm! Take a bathroom break or something. 🤣 This is the final stretch.

The last big piece of the puzzle is our Flipbook widget. It makes use of everything we've built so far.

Let's go straight to the code, looking at the widget class first:

class Flipbook extends StatefulWidget {
  final String title;
  final ThemeData? theme;
  final RouteMap routes;

  Flipbook({
    required this.routes,
    this.title = '',
    this.theme,
  });

  @override
  _FlipbookState createState() => _FlipbookState();
}

This is a simplified version, but normally this should include all the properties of MaterialApp that you need to define. Now on to the matching state class:

class _FlipbookState extends State<Flipbook> {
  final _routeParser = RouteParser();
  late final FlippinRouterDelegate _routerDelegate;

  @override
  void initState() {
    super.initState();
    _routerDelegate = FlippinRouterDelegate(widget.routes);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      title: widget.title,
      theme: widget.theme,
      routerDelegate: _routerDelegate,
      routeInformationParser: _routeParser,
    );
  }
}

Now one more little piece to complete the package. We need to create a BuildContext extension so that widgets can easily update the route state, i.e. context.route.setState(path):

extension RouteContext on BuildContext {
  RouteState get route => RouteState.instance;
}

That's it. Congratulations for finishing this challenge with me!

Further exploration...

We've built enough of our API to cover what we intended to build out, and hopefully it also gave us enough understanding of how Navigator 2.0 works.

However there is always room for our API to grow, unfortunately we don't have time/space to cover everything here. These are some of the things that you may want to further pursue, for learning, utility or just having fun:

nested routers
handling of the Android Back button
custom handling/animation of transitions

I have implemented these already, but I'll let you take the challenge first, and then I'll post a gist on GitHub soon. 🤓

Thank you for reading. I hope you gained something from this long journey.

Can React state management get any simpler than this?

Arnel Enero — Sun, 14 Mar 2021 19:08:27 +0000

I'm one that loves simplicity in things. So despite the plethora of state management libraries for React, I have always wondered what the absolute "simplest" approach would be.

After some time on the drawing board, I think I've come up with just that. And today I'm happy to share with you SimpleR State. (yes, with capital "R", for React 😂)

Imagine being able to implement shared state in just 2 easy steps!

Step 1: Create an entity (shared state) and actions (updater functions)

// counter.js

import { entity } from 'simpler-state'

export const counter = entity(0)

export const reset = () => {
  counter.set(0)
}

export const increment = by => {
  counter.set(value => value + by)  
}

Step 2: Use the entity in your components with hooks

import { counter, increment, reset } from 'counter'

const CounterView = () => {
  const count = counter.use()

  return (
    <>
      <div>{count}</div>

      <button onClick={() => increment(1)}> + </button> 
      <button onClick={reset}> Reset </button>
    </>
  )
}

(Other components can use the shared counter the same way.)

It's that simple! But that's just a teaser, it can actually do a whole lot more!

Here are some of the design goals for this library:

Minimalist API; no complicated concepts or boilerplate
Use plain functions to implement state changes (including async)
Largely unopinionated with flexible syntax
Extremely simple to unit test state changes
Highly extensible with plug-ins (e.g. persistence, logging, dev tools)
Full TypeScript support with uncomplicated types
Made specifically for React, and built on React Hooks
Multiple times faster than context/reducer solution
Tiny, just around 1 KB (minified + gzipped)

If these benefits interest you, give SimpleR State a try. You can learn more about other things you can do with it at simpler-state.js.org. Yes, I wrote full documentation! 🤓

And if you like this library, and/or the simplicity/concept behind it please give it a star on the GitHub repo to let me know. 😀👌

So tell me, can the library get any simpler than this? I'd love to hear your suggestions. Goal is to get it closer to its bold claim of "simplest", not to compete with other libraries as the "best".

I opened a Request For Comments (here) on GitHub. Your comments and suggestions would be greatly appreciated. Feel free to drop me a comment here 👇 too.

Another P.S. -- I have prior art called react-entities which has already been out for quite some time, and used by our company in production. SimpleR State is an evolution, based on the same stable core, but with completely different (much simpler) API.