Skip to content
This repository was archived by the owner on Feb 15, 2020. It is now read-only.

Update frameworks.md to suggest using React #201

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update frameworks.md to suggest using React #201

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 8 additions & 47 deletions pages/js/frameworks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@ layout: docs
sidenav: js
---
# Frameworks

**We recommend using [React]() for projects when possible.** As a team, we enjoy using React because it has a strong component model, enables easy server side rendering, and faciliates debugging by making the UI elements a function of the application state. React is most akin to the "view layer" in an MVC (Model-View-Controller) architecture and is frequently used with some other libraries. In our projects, we tend to use:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd feel more comfortable if rather than recommending one privately-owned framework, we instead suggest react-like frameworks, encompassing Preact and others built on the same-ish APIs.

I also think whole-heartedly endorsing redux may be overkill, and possilby bad advice. I think the current advice is usually "Use redux if you need to, and not if you don't"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the purposes of the guide is to document and suggest what tools we are currently using at 18F, and I think React falls within the scope of that. If there are other projects we can point to that actively support Preact then I feel we should add that in, but if we aren't using it then I don't think we should be supporting it as guidance.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see what you're saying, and it makes sense, but perhaps We recommend using React for projects when possible. is just a bit too strong.

While I like React quite a bit, and think it's perfectly fine, I have two issues with it as a recommendation:

  1. Given Facebook's ethical and privacy issues and questionable trademark history, I'd be hesitant to hitch my wagon so directly to them.
  2. Due the well-documented APIs, there are a whole host of React-like alternatives, many of which are drop-in replacements with much smaller footprints. Preact is only one of many, and I just mentioned it because it's among the best known (although some others are catching up quick) More info: https://hackernoon.com/the-react-is-dead-long-live-the-react-e97eea715f1c

My suggestion would be something along the lines of We recommend a React-compatible framework. We use React, but Preact, Inferno and others may be viable alternatives for your needs.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @xtine, @tbaxter-18f. This is a recommendation and not an enforcement. We only recommend xyz lib because that's what a majority of our projects are built with. We aren't using those other libraries here, but this is just guidance. It's not trying to enforce anything.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**We recommend using [React]() for projects when possible.** As a team, we enjoy using React because it has a strong component model, enables easy server side rendering, and faciliates debugging by making the UI elements a function of the application state. React is most akin to the "view layer" in an MVC (Model-View-Controller) architecture and is frequently used with some other libraries. In our projects, we tend to use:
**We recommend using [React](https://reactjs.org/) for projects when possible.** As a team, we enjoy using React because it has a strong component model, enables easy server side rendering, and faciliates debugging by making the UI elements a function of the application state. React is most akin to the "view layer" in an MVC (Model-View-Controller) architecture and is frequently used with some other libraries. In our projects, we tend to use:


* [Redux](https://www.npmjs.com/package/redux) for managing state
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can I suggest adding "optional" as simpler webapps may not need to rely on Redux?

* [Webpack](https://www.npmjs.com/package/webpack) and [Babel](https://babeljs.io/) for compiling our Javascript
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does react-router belong on this list, in a similarly "optional" bullet as Redux? Do we have a different routing library we like to use? Do we tend to roll our own (please no)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also curious if we want to recommend something like create-react-app to help bootstrap a new React project. Goodness knows setting up Webpack by hand is no fun. 😄


However, we are not dogmatic about React - we just vastly prefer it. Here are some other popular frameworks that have been used at 18F and some of their key characteristics.

## Angular
AngularJS (commonly referred to as "Angular") is an open-source web application framework maintained by Google and by a community of individual developers and corporations to address many of the challenges encountered in developing single-page applications ([Wikipedia](http://en.wikipedia.org/wiki/AngularJS)).

Expand Down Expand Up @@ -63,50 +71,3 @@ Backbone.js is a JavaScript library with a RESTful JSON interface and is based o
- Designed primarily for REST data.


## React
React (sometimes styled React.js or ReactJS) is an open-source JavaScript library for creating user interfaces that aims to address challenges encountered in developing single-page applications ([Wikipedia](https://en.wikipedia.org/wiki/React_(JavaScript_library))).

#### When to use:
- Single page apps that requires data manipulation on the front end without a server side request/response architecture.
- When there's a strong need to render JavaScript based UI on the server due to performance or accessibility reasons.
- JavaScript UI that incorperates many nested components.
- A UI with many components and updates that needs to be performance conscious.
- When only a "view" framework is desired/required.
- To ensure all front end components conform to a single standard.

#### When not to use:
- When a complex build process is not feasible. React requires transforming "jsx" files to regular JavaScript.
- When developers unfamiliar with JSX and don't have time to learn.
- While open source, is maintained primarily by Facebook.


## Flux
Flux is not a framework, nor is it M**VC. It's a software architecture for
writing complex single page applications.

#### When to use:
- A complex JavaScript app that requires both viewing and modifying (CRUD) data
in a UI rendered on the client. Flux will likely be overkill for apps that
don't modify data in any way.
- When the data service for the front end is REST and/or something besides REST,
such as Websockets.
- An app thats data flow has grown or will grow overly complex.

#### When not to use:
- Applications that don't require any updating (create, update, delete) of data.
- When the cost of updating an app's architecture to flux is more than the cost
of writing the software as it exists.

#### Pros:
- Easily add non-REST services to a front end, in a transparent way.
- Cleans up complex data flow by using uni-directional data flow.
- Cleans up complex async behavior and nested callbacks by using an evented
system and functionality to wait for data.
- Can use simple JavaScript objects rather than a complex framework.
- Easily tie components together in a clean way.
- Requires little 3rd party software.

#### Cons:
- More verbose in file and directory structure.
- Finding best way to use can be difficult for beginners.
- Can be hard to find a good structure when beginning.