Earth Dashboard features hundreds of data sets all in one place on the state of the planet’s resources and citizens. Users can visualize challenges facing people and the planet, from climate change to poverty, water risk to state instability, air pollution to human migration, and more.
Native execution requires the following:
Run
yarnin your terminal will install all dependencies. Once done, type:
yarn devand your app will be served in http://localhost:9000/ (if you didn't change the default port in the .env).
main: This is the production branch. The code from this branch should be deployable at any time.develop: This is the reference branch for development. This branch will be used for the staging site and all feature/bug branches should be created starting from it.
If you need a production-ready build, run:
yarn buildthis will generate your build in ./dist folder ready to run
Happy coding!
Deployment is done using Capistrano, a Ruby gem. It also requires you to have SSH access to the server using a public/private key pair.
Once you have Capistrano and its dependencies up and running, simply run:
bundle exec cap <environment> deployEach available environment will have a file with its name in the config/deploy folder.
The process may take a few minutes. The deployment is based of Github, not your local machine, so be sure to have the code you want to see live pushed to Github. You can continue editing your code locally while the deployment process takes place.
There's an .env.sample file you will need to duplicate and rename to .env in order to make the app work. Populate it properly and that's all.
You can find information there about the environment variables that are necessary for this project.
You might run into some problems installing dependencies:
If the installation fails at the point where it installs canvas, you may want to take a look at this.
The application is built on top of Next.js - a framework for server-rendered React apps. Next provides a zero-setup webpack build ready to develop along a express server to run the application and SASS styles compilation.
Earth Dashboard application is split into the next main folders:
- components
- css
- layout
- pages
- public
- redactions (legacy)
- selectors (legacy)
- services
- slices
- utils
Pages are the first component to be loaded according Next specification. They contain the layout to be loaded. They are also in charge of fetching data for that specific page.
There are the main pages/groups of pages:
- [topic]: contains the news page related to each specific topic
- index: homepage.
- about: about page (it's actually loading the homepage with the navigation menu open and the about tab selected).
- 404: custom page not found layout.
NOTE: The way pages and routing works have changed in the last versions of Next.js has changed in the most recent versions of the library. For more information about how this works in the version that ED uses - 9.5.3 please check the official routing documentation.
Apart from the custom pages, there exist the following 3 unique pages defined by Next:
Page overriding the default page initialization. The code included here applies to all the rest of pages defined for the app. Please refer to the Custom App section of the official documentation for more information about this.
Custom Document page used to augment the application's <html> and <body> tags. Please refer to the Custom Document section of the official documentation for more information about this.
Custom error page (only shown in production). Please refer to the Custom Error Page section of the official documentation for more information about this.
Layouts are the second component to be loaded as part of the page render process. They contain all components that will be displayed in the page. Layouts don't directly fetch data but rather wait for it. Internal components could ask for data though.
Every component will be contained in its own folder with its name. A basic component will contain the component itself (component.js) plus an entrypoint to it (index.js). If the component needs access to the store, we will provide it here, otherwise we will just import the component. Additional files would be component-name.module.scss (containing component-scoped styles), constants.js (component-scoped constants), and data.js (component-scoped data).
./components/sidebar/
./constants.js (not required)
./component.js (required)
./index.js (required)
./sidebar.module.scss (not required)
./data.js (not required)
Recommendation: Try to make stateless components (unless it's necessary for some reason). This will make components easier to track and reuse.
These two are legacy folders from RW that are necessary for the back office components to work. Please refer to the Resource Watch documentation for more information about this.
Contains generic application styles, grid, settings, mixins and anything style-related in a global scope. It also contains third-app components styles if needed.
Legacy note: you will notice some style definitions whose scope are the components themselves as part of the ./css/components folder. These however are RW migrated styles that were necessary for the back office to work properly. Please refer to the Resource Watch documentation for more information about this.
Services are in charge of connecting the application with external APIs/other services. Every service contains a set of fetches (usually based on CRUD), it's possible to extend them if needed, but take into account there shouldn't be any app-related logic here. Every fetch should be able to be used in any context.
Services are based on Axios to manage XMLHttpRequests/HTTP requests.
Services are split into entities (most of them coming from WRI API, feel free to create a new one if needed. Every fetch must be documented. You can find more info about it in the documentation section.
All request wrappers are implemented as standalone functions using Axios that can potentially be used anywhere without any initialization. Most - if not all - of them return promises that should be handled in order to retrieve the results or manage potential errors.
Contains general use functions that are used across the app. Like constants, think about the scope of your util before implementing it here, perhaps just adding it at component's level is enough.
Contains assets that are used across the app, like data, images, favicon, robots...
Earth Dashboard uses Redux together with @reduxjs/toolkit to manage the app state.
Connection to the store must be isolated from the component itself (separating presentation from logic).
import { connect } from "react-redux";
// component
import PagesShow from "./component";
export default connect(
state => ({
user: state.user,
id: state.routes.query.id
}),
null
)(PagesShow);The example above shows an index.js separating the logic from the component layout.
Authentication is based on the RW API user management API and it's handled entirely by the front-end. Check the methods from services/user and the user slice for more information about this.
We're using Fresnel -an SSR compatible approach to CSS, to manage the different versions of the interface depending on the device that's being used. Definitions of the breakpoints plus components that can be used to define the interface for each of the cases can be found on /utils/responsive
Bundle Analyzer is a development tool that creates an interactive treemap visualization of the contents of all your bundles.
To run it: yarn bundle-analyzer.
It will run the application in production build (makes a yarn build internally) and open a tab in your browser displaying the bundles treemap.