Welcome to Arks (unmaintained)

This the offical repository of the Arks framework.

!! This is for now an experimental project !!

What is Arks?

Arks is an opiniated open source (very important term) React framework for creating, developing, building and shipping isomorphics apps built on top of React Router and Apollo GraphQL.
So all of the parts of an Arks project is made to be used in a defined and strict context. Of course this context can evolves with time.
In a defined project structure the CLI will mount an Express server with some features for you and serves a server side rendered React App.
This is the main purpose of Arks: to let developers focusing more on the quick development of the React application without to be worried by the implementation of a server for enabling server side rendering with React Router and Apollo GraphQL.

The project is divided in several packages and the server comes with some features such as monitoring as it will explain below.

Arks is made to be driven by the community so please feel free to send us your feedback, ideas and PRs!

Table of Contents

• Getting Started
• Arks CLI
• Arks availables packages
• Arks project structure
• Arks configuration files
• Arks Express server
• Arks Apollo client
• Arks React application
• Design systems and stylesheets
• Samples
• Known Bugs
• Built With
• Authors

Getting Started

Here you can fin all the instructions you need to know to get started with Arks.

Prerequisites

• NodeJS version >= 12.16.3
• NPM version >= 6.13.0
• yarn yarn is not supported, please use npm

Installing the Arks CLI

You can install the Arks cli by running the following command:

npm install -g @arks/cli

Once the cli is installed you can go ahead to create an develop Arks projects.

Arks CLI

The CLI of Arks is based on NPM and with Commander.
You will find some commands like create, dev, build and start.

Help

If you need help the cli comes with it.
You can use the following command:

arks -h

Command: create

The create command is composed of sub commands which let you creating Arks project or objects such as components (incoming feature) into your project.

Creating a project

The first sub command of the create command is project.
This sub command will creates into a directory of the name of the project and then creates all the files needed for running an Arks project and install the node_modules.

Command:

arks create project <name>

Args:

Name	Description	Type	Default Value	Required
name	name of the project	string		yes

Command: dev

The dev command let you start an Arks project as development.
It will creates a webpack dev compiler with hot reloading for client side rendering and server side rendering, then creates and starts an Express server.

Command:

arks dev -p 8080

Options:

Name	Alias	Description	Type	Default Value	Required
--port	-p	Specific port to use	string	8080	no
--host	-s	Specific host to use	string	0.0.0.0	no
--protocol	-p	Specific protocol to use	string	http	no

Command: build

The build command will build and Arks project as production.
It will makes two builds. One for client side rendering and on for server side rendering.

Command:

arks build

Options:

Name	Alias	Description	Type	Default Value	Required
--use-source-map		Use source map for debugging production build	boolean	false	no

Command: start

The start command let you start an Arks project as production.
It creates and starts an Express server, and then serves the application built for server side rendering and client side rendering.

Command:

arks start

Options:

Name	Alias	Description	Type	Default Value	Required
--port	-p	Specific port to use	string	8080	no
--host	-s	Specific host to use	string	0.0.0.0	no
--protocol	-p	Specific protocol to use	string	http	no
--open	-o	Opening a web browser for testing production build on a local machine	boolean	false	no

Arks availables packages

Here is the list of all availbles and packages :

Name	Description	Implemented
cli	Arks command line interface	Yes
schematics	Arks project schematics	Yes
utils	Some utils	Yes
misc	Misc things	Yes
common	Some commons used in the other pakcages	Yes
monitors	Monitors used in an Arks server	Yes
logger	Arks custom logger	Yes
compiler	Arks webpack compiler	Yes
config	Arks config	Yes
server	Arks server implementation	Yes
builder	Arks builder implementation	Yes
creator	Arks creator implementation	Yes
schematics	Arks schematics implementation	Yes
client	Arks browser clients functions and components	Yes
react	Arks React components, hooks, utilities, ...	Partial

Arks project structure

When creating an Arks project the cli will creates into the file system of your machine the following files and directories :

Name	Description
tsconfig.json	The TypeScript config for compiling sources
package.json	The classic package file for npm
globals.d.ts	Extra types definition
.gitignore	Basic .gitignore file
.env	Environment configuration file for emulating env vars
arks.json	Arks configuration file for configuring an Arks project
public/	A directory for serving static files throught the public route /public
src/	React application sources directory
src/app.tsx	Arks React application file
src/pages	Directory to store pages of an Arks React application - Some pages are already availables when creating an Arks project such as Home or NotFound
.arks/	Directory where the Arks cli will perform actions for compiling an Arks React application

Arks configuration files

In an Arks project you can configure your application with a .env file for environment configuration and a arks.json file for project configuration.

Environment configuration

As said below onto your local machine or into your deployment environment you can emulate environment vars with an .env file.
Here's the list of environment vars supported for now by Arks:

Name	Description	Type	Default value
PORT	Port to use to serve the Arks project - It will be overrided if the port is specified into the cli command	string	8080
GRAPHQL_API_ENDPOINT	The endpoint to reach fir executing GraphQL requests	string
HOST	Host to use to serve the Arks project - It will be overried if the host is specified into the cli command	string	0.0.0.0
PROTOCOL	Protocol to use to serve the Arks project - It will be overried if the host is specified into the cli command	string	http
METRICS_COLLECT_TIMEOUT	Time interval to collect metrics of the NodeJS process with Prometheus	string	5000
HTTP_TIMEOUT	Http timeout for http requests	string	10000
LIMIT_WINDOWS_TIME_FRAME_MS	Time frame limit for requesting the Arks Express application - "express-rate-limit" middleware	string	900000
LIMIT_MAX_REQUESTS_PER_IP	Number of requests per IP for requesting the Arks Express application into the time frame - "express-rate-limit" middleware	string	200

Arks json file configuration

You can canfigure some properties of your Arks project with and arks.json file.
Here's the list of properties supported for now by Arks:

{
  // Application name
  "appName": "string",
  
  // Disabling monitoring metrics collection 
  "noMetrics": boolean,

  // Disabing liveness route for healthchecks
  "noLiveness": boolean,

  // Customizing the metrics collection endpoint for monitoring
  "metricsEndpoint": "string",

  // Customizing the liveness endpoint for healthchecks
  "livenessEndpoint": "string",

  // Disabling the "helmet" middleware (security)
  "noHelmet": boolean,

  // Disabling the "cors" middleware (security)
  "noCors": boolean,

  // Disabling the "express-rate-limit" middleware (security)
  "noLimit": boolean,

  // Disabling the "body-parser" middleware
  "noBodyParser": boolean,

  // Disabling the "cookie-parser" middleware
  "noCookieParser": boolean,

  // Disabling the "compression" middleware
  "noCompression": boolean,

  // Disabling Arks logger (not interpreted for now)
  "noLogger": boolean,
}

Arks Express server

The Arks Express server is only handle by the Aks cli.
In no way it can be overrided!

The Arks Express server is mount based on the .env and arks.json file. If no configuration is provided Akrs will use default constants as you can see here.
The server comes with some feature for monitoring or healthchecks.

Features:

Name	Description	Configurable
Metrics	Exposing NodeJS process metrics with Prometheus on the /metrics endpoint	Yes - Disabling, endpoint customization and metrics collection timeout customization
Liveness	Exposing a simple endpoint responding a status with an "alive" text for healthchecks	Yes - Disabling or endpoint customization
Security	Using some security configs	Yes - please refer to the Arks configuration files below
Middlewares	Using some middlewares configs	Yes - please refer to the Arks configuration files below
GraphQL Proxy	Proxying the given GraphQL Endpoint	No

Exposed routes:

Name	Description
/metrics	Metrics route collection
/liveness	Liveness route
/graphql	GraphQL endpoint
/public	Endpoint for serving static content
/build	Endpoint for serving the built client JavaScript bundle React application as production
/	Endpoint for serving the server side rendered React Application

Arks Apollo client

Into an Arks project an Arks Apollo client is created for client side rendering and server side rendering.
For security concerns, the GraphQL endpoint defined in the .env configuration file is proxyfied. This means the Arks React application never reachs the GraphQL endpoint in first but instead it will reach the route /graphql exposed by the Arks Express server which is the proxy entry point.
So your GraphQL endpoint is always protected and never exposed into the web browser.

It no GRAPHQL_ENDPOINT property is defined in the .env configuration file, the Arks Express server will not create a proxy but instead will respond at the /graphql an empty JSON object.

Arks React application

Into an Akrs project, the Arks React application is made to simple to use and to implement.
Into the src/ directory you will the mandatory file app.tsx. This file is used by the server webpack and the client webpack compilers! If you deleted Arks will not be able to compile and serves your React application. And the App component as to be always exported as default!

import * as React from 'react';
import { Switch, Route } from 'react-router-dom';

import { 
    Home,
    Help,
    NotFound,
} from './pages';

export default function App(): React.ReactElement {
    return (
        <Switch>
            <Route exact path='/'>
                <Home />
            </Route>
            <Route path='/help'>
                <Help />
            </Route>
            <Route path='*'>
                <NotFound />
            </Route>
        </Switch>
    );
}

As you can understand this is mandatory file!
Page components are under the src/pages/ directory.

In the future the Arks React application will be shape with more sturucted directories and files!

Design systems and stylesheets

For now the Arks webpack compiler is not made to support stylesheets compilation, this feature will come maybe in the future.
Arks is made to be more focused of the development of an React application's logic and performance. So if you want some styles into your Arks React Application it's mandatory to use a design system with css-in-js such as Chakra UI.
Soon Arks will provide an official support for design systems with samples.

Samples

You can find a bunch of samples in the samples directory of the project.

Known Bugs

Here is the list of known bugs of Arks :

Name	Description	Corrected
React hot loader not detected	False/true - Present and functionnal but not detected	No
SSR Matching	After webpack compliation for SSR React trees doesn't match	No

Built with

• TypeScript
• React
• React Router
• Apollo GraphQL
• Webpack
• Express
• NodeJS
• Prometheus
• Commander
• Angular DevKit
• Angular DevKit Schematics
• Gulp

Authors

• Aurélien Dupays Dexemple

This project is made with ♥ and under the MIT License.