Home

Awesome

<a href="https://unly.org"><img src="https://storage.googleapis.com/unly/images/ICON_UNLY.png" align="right" height="20" alt="Unly logo" title="Unly logo" /></a> Maintainability Test Coverage

Status: STABLE/POC/NON-MAINTAINED

Our motivations

We wanted to build our own admin backoffice to manage our content. But the task has revealed itself much more complicated than what I thought it'd be.

Want to contribute? Kept for reference, but do not expect any involvement from us

  1. Check our roadmap to get an overview of what we want to build with NRN-Admin
  2. Check what's left to do for v1 release
  3. Check our Community open discussion for v1 and share your thoughts, questions, etc.
  4. Check open issues for v1 and let us know what you'd like to work on. Make sure you understand the specs properly before starting, don't hesitate to ask for clarifications if unclear.

Next Right Now Admin

Next Right Now Admin is a boilerplate to quickly build an Admin frontend, based on NRN and react-admin

Benefits

<!-- toc --> <!-- tocstop -->

Getting started

Showcases - Live demo

https://nrn-admin.unly.now.sh/

Tip: You can get metadata at /api/status

Tip: All /api/* are serverless functions, running under AWS Lambda

Super quick local installation (for local-only testing purpose, without Zeit account)

This assumes you've cloned the project on your own computer.

Follow this guide if you just want to try it out on your local machine

Tip: Using now@17+ is required for CI to work properly, but you don't care about that if you just want to get started quickly.

Tip: You can start the project in debug mode (built-in for WebStorm only) by running the WebStorm "Debug" configuration in debug mode

Tip: If there are tools that you don't need/like, read our guide about how to remove them.

Online installation (on Zeit)

If you want to deploy your local project online, run yarn deploy:production.

You will likely need to run now first, to authenticate and such. Also, you need to define the secrets (see Zeit advanced configuration guide).

Zeit advanced configuration guide

See https://github.com/UnlyEd/next-right-now/blob/master/README_HOW_TO_USE.md#online-installation-on-zeit

Steps are similar. This NRN-Admin doesn't use Locize though, so you can skip it.

Understanding Environments and Stages

The application relies on environment variables to function correctly. Those variables are provided differently depending on the environment.

When working on the development environment (localhost), the variables from .env.build are used by the webpack configuration

When deploying an instance to the Zeit's platform, the variables used are the one that belong to that instance, such as:

In those files, it's the build.env part that is used at build time (build is done on Zeit), which basically replaces all references of every environment variable by the actual value (string replace).

What is an environment?

An environment is "where" the application is running. It can be either "development" (localhost) or "production" (on Zeit's servers).

The environment is defined by the NODE_ENV environment variable.

N.B: It is not possible to any other value, as enforced by Next

When working on your local computer, you automatically use NODE_ENV=developement.

The environment affects how the application is bundled, it is used at build time. (webpack, hot-reloading, etc.)

i.e: In development environment, you have access to PropTypes warnings, but you won't in production.

What is a stage?

A stage is "how" the application is running. It can be either "development" (localhost), "staging" or "production" (on Zeit's servers) - You can add more if you need

The stage is defined by the APP_STAGE environment variable.

N.B: You can use any stage name you like, there is no restriction.

The stage changes the behaviour of the application, because we sometimes need the application to behave differently depending on the stage.

i.e: In production stage, the Locize configuration uses the production version. When using another stage, it uses the latest version.

i.e: We don't want to enable the same level of debugging in production environment. For instance, Locize is configured to be in debug mode only in non-production stages.

I18n (Internationalization)

GraphCMS

Discount

Using the coupon code unly-nrn will grant you a 3-month 15% discount on the premium plans.

Fetching data from GraphCMS

TODO

Amplitude (Analytics)

Amplitude is used to collect usage metrics (analytics) of the application.

Amplitude is used only on the frontend part of the application. It is composed of two parts:

See the documentation example at react-amplitude to understand how it's meant to be used. We only use react-amplitude to manipulate events.

Known limitation: Amplitude doesn't provide any backend-compatible API. See https://github.com/amplitude/Amplitude-JavaScript/issues/164

Chrome developer debug tool

The amplitude team has released a Chrome plugin to see the events from the browser.

It is a must-have when working with Amplitude. It's very simple to use and quite helpful.

Continuous Integration & Continuous Deployment (CI/CD)

Overview

Every time a commit is pushed to the repository, or a branch is merged, automated actions are triggered.

Those actions are managed through Github Actions

Workflow of our Zeit <> Github Actions integration

Here is how the multiple steps are ordered:

  1. [Event] A commit is pushed, a branch is merged (or on any change made on the remote repository)
  2. [Trigger] Our Github Actions are triggered
    • Either the staging scripts is executed, or the production script, depending on which branch is impacted (see Github Actions <> Zeit integrations)
    • No matter what script (production vs staging) gets executed, those actions are always triggered:
      1. A new Zeit deployment is triggered, which runs our tests first (yarn test:once) (Failing tests will stop the deployment)
      2. Then, the deployment is deployed, and automatically linked to a custom domain which depends on the git branch name (xxx.now.sh)
      3. Then, our 2E2 tests are triggered using Cypress
        • If they fail, artifacts (screenshots, videos) recorded by Cypress are uploaded to Github to help further debug (See example)

In-depth project's dependencies

See README_DEPENDENCIES

Testing

CI tests Workflow

Zeit will automatically run the tests before deploying, as configured in the yarn build command.

If any test fail, the deployment will be aborted. This ensures that any code that doesn't pass the tests never get deployed online.

Once a deployment has been deployed on Zeit, Github Actions will run our E2E tests, to make sure that the app behaves as expected. This can also be considered as an integration tests suite.

Running tests manually (locally)

You can run interactive tests using Jest with yarn test script.

Running E2E tests manually (locally)

You can run interactive E2E tests using Cypress with yarn e2e:open script.

You can also run them non-interactively using yarn e2e:run script.

You may need to run yarn e2e:install script first

Project folders structure

Overview of the project folder and files structure

License

MIT

Vulnerability disclosure

See our policy.

Contributors and maintainers

This project is being maintained by:

Special thanks to:

[ABOUT UNLY] <a href="https://unly.org"><img src="https://storage.googleapis.com/unly/images/ICON_UNLY.png" height="40" align="right" alt="Unly logo" title="Unly logo" /></a>

Unly is a socially responsible company, fighting inequality and facilitating access to higher education. Unly is committed to making education more inclusive, through responsible funding for students.

We provide technological solutions to help students find the necessary funding for their studies.

We proudly participate in many TechForGood initiatives. To support and learn more about our actions to make education accessible, visit :

Tech tips and tricks from our CTO on our Medium page!

#TECHFORGOOD #EDUCATIONFORALL