Link Search Menu Expand Document
Next Right Now

Dependencies

Overview of the project dependencies, why we use them, and quick explanations about them

All the packages listed here are under open source, non-restrictive license (MIT, ISC, etc.)

The order follows the order in package.json (kinda alphabetical but not quite exactly ¯\_(ツ)_/¯)

Only the common dependencies are listed here, not vendor-related dependencies.

Vendor-related dependencies are listed per-vendor, in their respective “How to use” guide.

Table of contents

Dependencies

Dependencies that are bundled to the end-user app.

FortAwesome/FontAwesome

FontAwesome is an awesome icon toolkit.

NRN uses the free version, but we managed to use the paid version on some other app (cloned from NRN), it’s not an issue, just harder to configure.

Installation tutorial

Note about FontAwesome usage

FontAwesome is a little trickier to use that we would like to.

For any icon you want to use, you must first load it through the src/pages/_app.tsx file and then load it in the FA library, as follow:

```typescript jsx import { config, library } from ‘@fortawesome/fontawesome-svg-core’; import { faGithub } from ‘@fortawesome/free-brands-svg-icons’;

library.add(faGithub);


> This operation is required in order to make the FA icon load properly on the server side

Then, you can use those icons in any react component:

```typescript jsx
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';

// Inside a react component
<FontAwesomeIcon icon={['fab', 'github']} />

Our @unly packages

We use some of our own packages made @unly.

They are all hosted on ou GitHub repository, and all under open source license.

  • @unly/utils: This is a utility library which contains various helpers. This repository was created because those helpers are used amongst several projects and were copy/pasted, which is a bad practice.
  • @unly/utils-simple-logger: Logger based on Winston with sane default so that it only logs error in production and filter other logs, while keeping them all in non-production environments. Basically avoids to increase cost by logging useless logs in production.
  • @unly/universal-language-detector: Language detector that works universally (browser + server) - Meant to be used with a universal framework, such as Next.js

Feel free not to use them.

@unly/universal-language-detector is necessary for SSR language detection, you won’t need it if not using SSR.

Bootstrap & Reactstrap

We use Reactstrap as a Components library, which is itself based on Bootstrap.

Notes about Bootstrap/Reactstrap usage

We are not quite satisfied with Reactstrap, to be honest. But we haven’t found a better alternative so far (mostly because we’re used to bootstrap, and lack of time for R&D).

It does the job, but we dislike it more and more.

Alternatives to Bootstrap/Reactstrap may be:

Both look like promising CSS frameworks, there is likely more of them out there, but that’s our top 2 in early 2020.

Notes about Reactstrap Tooltips and Modal (SSR-not-friendly)

We strongly suggest using another lib for Tooltips such as rc-tooltip.

Known issues:

classnames

classnames is just the must-have tool to use to manipulate dynamic className property

  • classnames: A simple JavaScript utility for conditionally joining classNames together.

Cookies

It’s hard (or at least, non-trivial) to make cookies work universally with Next.js

  • js-cookie: Used to WRITE cookies from the client side. A simple, lightweight JavaScript API for handling browser cookies
  • cookies: Used to WRITE cookies from the server side. Cookies is a node.js module for getting and setting HTTP(S) cookies. Cookies can be signed to prevent tampering, using Keygrip. It can be used with the built-in node.js HTTP library, or as Connect/Express middleware. I’m not sure if that lib is the best choice, but it did work back then. Other alternative may be https://github.com/maticzav/nookies
  • next-cookies: Used to READ cookies universally (cannot write). Tiny little function for getting cookies on both client & server with next.js. This enables easy client-side and server-side rendering of pages that depend on cookies.

A cookies prop is available to all Page and Layout components (through the _app.tsx:render()).

universal-cookie looks promising and if you know about it, you may ask yourself why we don’t use it instead of one package for the client side, and another one for the server side.

Well, the answer is straightforward: It does not work. See https://github.com/reactivestack/cookies/issues/256

Cookies management abstraction UniversalCookiesManager

We’ve built our own UniversalCookiesManager utility class to deal with cookies in a universal way (same API on client/server sides).

It basically hides away the complexity, and allows for source code reusability.

css-to-react-native

Converts CSS text to a React Native stylesheet object.

Converts all number-like values to numbers, and string-like to strings.

Automatically converts indirect values to their React Native equivalents.

Used to dynamically convert CSS to React style object, for CSS rules coming from a data source (such as GraphCMS).

Currently used by GraphCMSAsset.tsx

deepmerge

Merges the enumerable properties of two or more objects deeply.

Used in many places to merge different objects together. Handles deeply nested objects.

isomorphic-unfetch

Can be used to either polyfill the whole app, or used as a fetch function. (Stands for “isomorphic universal fetch”)

There are several libs to allow fetching data from a react app, here is a comparison.

The main reason for choosing this one is its very small bundle size, and it’s universal.

json-stringify-safe

Used to safely stringify JSON objects. Works even when they have circular dependencies

Use at your convenience. We weren’t sure whether to use json-stringify-safe or safe-json-stringify and we made a wild choice here.

Lodash

A modern JavaScript utility library delivering modularity, performance & extras.

We made the choice to import lodash packages one-by-one instead of loading the whole lodash lib directly. We’re not sure if it’s better/easier/wiser. We suppose it should decrease the bundle size, but maybe it’s natively handled by tree-shacking?

We use plenty of utilities from lodash. Make sure read their documentation.

Note about Lodash TS typings

We also load each TS types one-by-one. One advantage of that is that we can decide not to load typings that do not work.

For instance, we tried using @types/lodash.filter but eventually removed it because it creates a mess that is hard to deal with. Typings may be wrong and breaks our tests, in such case it’s nice to have the flexibility not to use them.

Next

Next.js framework package and plugins/utilities.

rc-tooltip

React Tooltip component

Marked as alpha-3 version but stable. Much better than Reactstrap Tooltip component.

React

React package and plugins/utilities.

  • react: React is a JavaScript library for creating user interfaces.
  • react-apollo: React Apollo allows you to fetch data from your GraphQL server and use it in building complex and reactive UIs using the React framework. React Apollo may be used in any context that React may be used. In the browser, in React Native, or in Node.js when you want to do server-side rendering.
  • react-dom: This package serves as the entry point to the DOM and server renderers for React. It is intended to be paired with the generic React package, which is shipped as react to npm.
  • react-style-proptype: Validates style objects by ensuring the keys are valid css property names (in camelcase form).
  • prop-types: Runtime type checking for React props and similar objects.

Tip: react and react-dom must always use the same version.

recompose

Used to compose multiple HOC together

  • recompose: Recompose is a React utility belt for function components and higher-order components.

webfontloader

Web Font Loader gives you added control when using linked fonts via @font-face.

It provides a common interface to loading fonts regardless of the source, then adds a standard set of events you may use to control the loading experience.

The Web Font Loader is able to load fonts from Google Fonts, Typekit, Fonts.com, and Fontdeck, as well as self-hosted web fonts. It is co-developed by Google and Typekit.

winston

Peer-dependency of @unly/utils-simple-logger

  • winston: A logger for just about everything.

Dev dependencies

Development dependencies that are required to run the program locally (the bundle won’t contains these dependencies).

@types

TypeScript requires Typings to resolve types.

Those packages add additional types that allow TypeScript to resolve the related types, and allow for a better developer experience. Also, without some of those types, TS would fail to compile.

Sometimes, TS types are included in the same package as the main package, sometimes in a different package, such as for those below.

Those dependencies are used only during the development and aren’t shipped to the end-user.

They are meant to make the development process easier/faster.

Vercel

Official packages from Vercel, the company hosting our application

Debug WebStorm

Packages meant to help with the debug of the application

  • concurrently: Run multiple commands concurrently.
  • cross-env: Run scripts that set and use environment variables across platforms.

Together, those two packages are used by the WebStorm “Debug” configuration. (top right)

Running the Debug configuration in debug mode allows to pause execution and use breakpoints.

Eslint

Eslint helps us enforce code style and check for typos and errors during the development process

Eslint rules are automatically used by WebStorm.

Eslint with TypeScript and JSX support was configured following this tutorial.

Run yarn lint to run the linter.

Documentation

  • markdown-toc: Generate a markdown TOC (table of contents). Uses many dependencies, many of them outdated (handlebars) and containing security issues, but we don’t care much about those as they aren’t shipped in the build, but only present on the developer’s local machine.
  • version-bump-prompt: Used to make it easier to bump versions.