{"id":15169712,"url":"https://github.com/sugardarius/arks","last_synced_at":"2025-10-01T02:31:41.678Z","repository":{"id":42231898,"uuid":"266577521","full_name":"SugarDarius/arks","owner":"SugarDarius","description":"An opiniated React framework for isomorphic apps built on top of React with React Router and Apollo GraphQL","archived":true,"fork":false,"pushed_at":"2024-05-02T14:29:32.000Z","size":928,"stargazers_count":2,"open_issues_count":17,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-26T10:54:28.440Z","etag":null,"topics":["apollo","express","graphql","isomorphic","nodejs","react","react-router","server-side-rendering","typescript","typescript-framework"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SugarDarius.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-24T16:11:53.000Z","updated_at":"2024-05-02T14:30:45.000Z","dependencies_parsed_at":"2024-09-22T15:01:00.556Z","dependency_job_id":null,"html_url":"https://github.com/SugarDarius/arks","commit_stats":{"total_commits":104,"total_committers":3,"mean_commits":"34.666666666666664","dds":0.05769230769230771,"last_synced_commit":"4d6b218fb27829a8907a33099dee5289c165bee4"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SugarDarius%2Farks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SugarDarius%2Farks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SugarDarius%2Farks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SugarDarius%2Farks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SugarDarius","download_url":"https://codeload.github.com/SugarDarius/arks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219875271,"owners_count":16554661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apollo","express","graphql","isomorphic","nodejs","react","react-router","server-side-rendering","typescript","typescript-framework"],"created_at":"2024-09-27T07:21:29.066Z","updated_at":"2025-10-01T02:31:36.198Z","avatar_url":"https://github.com/SugarDarius.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"https://github.com/SugarDarius/arks\"\u003eWelcome to Arks (unmaintained)\u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"400\" align=\"center\" src=\"https://raw.githubusercontent.com/SugarDarius/arks/master/medias/img/arks-logo.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  This the offical repository of the Arks framework.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg align=\"center\" alt=\"GitHub package.json version\" src=\"https://img.shields.io/github/package-json/v/SugarDarius/arks\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GitHub issues\" src=\"https://img.shields.io/github/issues-raw/SugarDarius/arks\"\u003e\n  \u003ca href=\"https://github.com/SugarDarius/arks/blob/master/LICENSE\"\u003e\n    \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/SugarDarius/arks\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://lerna.js.org/\"\u003e\n    \u003cimg alt=\"With Lerna\" src=\"https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://twitter.com/azeldvin\"\u003e  \n    \u003cimg alt=\"Twitter Follow\" src=\"https://img.shields.io/twitter/follow/azeldvin?style=social\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n**!! This is for now an experimental project !!**\n\n## What is Arks?\nArks is an **opiniated** open source (very important term) [React](https://reactjs.org/) framework for creating, developing, building and shipping isomorphics apps built on top of [React Router](https://reacttraining.com/react-router/web/guides/quick-start) and [Apollo GraphQL](https://www.apollographql.com/).\u003cbr /\u003e\nSo 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.\u003cbr /\u003e\nIn a defined project structure the CLI will mount an [Express](http://expressjs.com/) server with some features for you and serves a server side rendered React App.\u003cbr /\u003e\nThis 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](https://reacttraining.com/react-router/web/guides/quick-start) and [Apollo GraphQL](https://www.apollographql.com/).\n\nThe project is divided in several packages and the server comes with some features such as monitoring as it will explain below.\n\nArks is made to be driven by the community so please feel free to send us your feedback, ideas and PRs!\n\n## Table of Contents\n\n- [Getting Started](#getting-started)\n- [Arks CLI](#arks-cli)\n- [Arks availables packages](#arks-availables-packages)\n- [Arks project structure](#arks-project-structure)\n- [Arks configuration files](#arks-configuration-files)\n- [Arks Express server](#arks-express-server)\n- [Arks Apollo client](#arks-apollo-client)\n- [Arks React application](#arks-react-application)\n- [Design systems and stylesheets](#design-systems-and-stylesheets)\n- [Samples](#samples)\n- [Known Bugs](known-bugs)\n- [Built With](#built-with)\n- [Authors](#authors)\n\n## Getting Started\nHere you can fin all the instructions you need to know to get started with Arks.\n\n### Prerequisites\n\n*  **NodeJS** version \u003e= 12.16.3\n*  **NPM** version \u003e= 6.13.0\n*  **yarn** yarn is not supported, please use npm\n\n### Installing the Arks CLI\nYou can install the Arks cli by running the following command:\n```bash\nnpm install -g @arks/cli\n```\nOnce the cli is installed you can go ahead to create an develop Arks projects.\n\n## Arks CLI\nThe CLI of Arks is based on NPM and with [Commander](https://github.com/tj/commander.js).\u003cbr /\u003e\nYou will find some commands like **create**, **dev**, **build** and **start**.\n\n### Help\nIf you need help the cli comes with it.\u003cbr /\u003e\nYou can use the following command:\n\n```bash\narks -h\n```\n\n### Command: `create`\nThe **create** command is composed of sub commands which let you creating Arks project or objects such as components (incoming feature) into your project.\n\n#### Creating a project\nThe first sub command of the create command is *project*.\u003cbr /\u003e\nThis 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.\n\nCommand: \n```bash\narks create project \u003cname\u003e\n```\nArgs:\n| Name                            | Description         | Type           | Default Value  | Required |\n| ------------------------------- | ------------------- |--------------- | -------------- | -------- |\n| name                            | name of the project | string         |                | yes      |\n\n### Command: `dev`\nThe **dev** command let you start an Arks project as development.\u003cbr /\u003e\nIt will creates a webpack dev compiler with hot reloading for client side rendering and server side rendering, then creates and starts an Express server.\n\nCommand:\n```bash\narks dev -p 8080\n```\nOptions:\n| Name                            | Alias           | Description              | Type    | Default Value  | Required |\n| ------------------------------- | --------------- | ------------------------ | ------- | -------------- | -------- |\n| --port                          | -p              | Specific port to use     | string  | 8080           | no       |\n| --host                          | -s              | Specific host to use     | string  | 0.0.0.0        | no       |\n| --protocol                      | -p              | Specific protocol to use | string  | http           | no       |\n\n### Command: `build` \nThe **build** command will build and Arks project as production.\u003cbr /\u003e\nIt will makes two builds. One for client side rendering and on for server side rendering.\n\nCommand: \n```bash\narks build\n```\nOptions:\n| Name                            | Alias           | Description                                       | Type    | Default Value  | Required |\n| ------------------------------- | --------------- | ------------------------------------------------- | ------- | -------------- | -------- |\n| --use-source-map                |                 | Use source map for debugging production build     | boolean | false          | no       |\n\n### Command: `start`\nThe **start** command let you start an Arks project as production.\u003cbr /\u003e\nIt creates and starts an Express server, and then serves the application built for server side rendering and client side rendering.\n\nCommand:\n```bash\narks start\n```\nOptions:\n| Name                            | Alias           | Description                                                           | Type    | Default Value  | Required |\n| ------------------------------- | --------------- | --------------------------------------------------------------------- | ------- | -------------- | -------- |\n| --port                          | -p              | Specific port to use                                                  | string  | 8080           | no       |\n| --host                          | -s              | Specific host to use                                                  | string  | 0.0.0.0        | no       |\n| --protocol                      | -p              | Specific protocol to use                                              | string  | http           | no       |\n| --open                          | -o              | Opening a web browser for testing production build on a local machine | boolean | false          | no       |\n\n## Arks availables packages\nHere is the list of all availbles and packages :\n\n| Name                            | Description                                                 | Implemented    |\n| ------------------------------- | ----------------------------------------------------------- | -------------: |\n| cli                             | Arks command line interface                                 | Yes            |\n| schematics                      | Arks project schematics                                     | Yes            |\n| utils                           | Some utils                                                  | Yes            |\n| misc                            | Misc things                                                 | Yes            |\n| common                          | Some commons used in the other pakcages                     | Yes            |\n| monitors                        | Monitors used in an Arks server                             | Yes            |\n| logger                          | Arks custom logger                                          | Yes            |\n| compiler                        | Arks webpack compiler                                       | Yes            |\n| config                          | Arks config                                                 | Yes            |\n| server                          | Arks server implementation                                  | Yes            |\n| builder                         | Arks builder implementation                                 | Yes            |\n| creator                         | Arks creator implementation                                 | Yes            |\n| schematics                      | Arks schematics implementation                              | Yes            |\n| client                          | Arks browser clients functions and components               | Yes            |\n| react                           | Arks React components, hooks, utilities, ...                | Partial        |\n\n## Arks project structure\nWhen creating an Arks project the cli will creates into the file system of your machine the following files and directories :\n\n| Name          | Description                                                                                                                                      |\n| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| tsconfig.json | The TypeScript config for compiling sources                                                                                                      |\n| package.json  | The classic package file for npm                                                                                                                 |\n| globals.d.ts  | Extra types definition                                                                                                                           |\n| .gitignore    | Basic .gitignore file                                                                                                                            |\n| .env          | Environment configuration file for emulating env vars                                                                                            |\n| arks.json     | Arks configuration file for configuring an Arks project                                                                                          |\n| public/       | A directory for serving static files throught the public route /public                                                                           |\n| src/          | React application sources directory                                                                                                              |\n| src/app.tsx   | Arks React application file                                                                                                                      |\n| 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 |\n| .arks/        | Directory where the Arks cli will perform actions for compiling an Arks React application                                                        |\n\n## Arks configuration files\nIn an Arks project you can configure your application with a **.env** file for environment configuration and a **arks.json** file for project configuration.\n\n### Environment configuration\nAs said below onto your local machine or into your deployment environment you can emulate environment vars with an **.env file**.\u003cbr /\u003e\nHere's the list of environment vars supported for now by Arks: \n\n| Name                        | Description                                                                                                                 | Type   | Default value |\n| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------ | ------------- |\n| PORT                        | Port to use to serve the Arks project - It will be overrided if the port is specified into the cli command                  | string | 8080          |\n| GRAPHQL_API_ENDPOINT        | The endpoint to reach fir executing GraphQL requests                                                                        | string |               |\n| 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       |\n| PROTOCOL                    | Protocol to use to serve the Arks project - It will be overried if the host is specified into the cli command               | string | http          |\n| METRICS_COLLECT_TIMEOUT     | Time interval to collect metrics of the NodeJS process with [Prometheus](https://prometheus.io/)                            | string | 5000          |\n| HTTP_TIMEOUT                | Http timeout for http requests                                                                                              | string | 10000         |\n| LIMIT_WINDOWS_TIME_FRAME_MS | Time frame limit for requesting the Arks Express application - \"express-rate-limit\" middleware                              | string | 900000        |\n| 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           |\n\n### Arks json file configuration\nYou can canfigure some properties of your Arks project with and **arks.json** file.\u003cbr /\u003e\nHere's the list of properties supported for now by Arks:\n\n```javascript\n{\n  // Application name\n  \"appName\": \"string\",\n  \n  // Disabling monitoring metrics collection \n  \"noMetrics\": boolean,\n\n  // Disabing liveness route for healthchecks\n  \"noLiveness\": boolean,\n\n  // Customizing the metrics collection endpoint for monitoring\n  \"metricsEndpoint\": \"string\",\n\n  // Customizing the liveness endpoint for healthchecks\n  \"livenessEndpoint\": \"string\",\n\n  // Disabling the \"helmet\" middleware (security)\n  \"noHelmet\": boolean,\n\n  // Disabling the \"cors\" middleware (security)\n  \"noCors\": boolean,\n\n  // Disabling the \"express-rate-limit\" middleware (security)\n  \"noLimit\": boolean,\n\n  // Disabling the \"body-parser\" middleware\n  \"noBodyParser\": boolean,\n\n  // Disabling the \"cookie-parser\" middleware\n  \"noCookieParser\": boolean,\n\n  // Disabling the \"compression\" middleware\n  \"noCompression\": boolean,\n\n  // Disabling Arks logger (not interpreted for now)\n  \"noLogger\": boolean,\n}\n```\n\n## Arks Express server\nThe Arks Express server is only handle by the Aks cli.\u003cbr /\u003e\n**In no way it can be overrided!**\n\nThe 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](./packages/config/constants.ts).\u003cbr /\u003e\nThe server comes with some feature for monitoring or healthchecks.\n\nFeatures:\n| Name          | Description                                                                                        | Configurable                                                                          |\n| ------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| Metrics       | Exposing NodeJS process metrics with [Prometheus](https://prometheus.io/) on the /metrics endpoint | Yes - Disabling, endpoint customization and metrics collection timeout customization  |\n| Liveness      | Exposing a simple endpoint responding a status with an \"alive\" text for healthchecks               | Yes - Disabling or endpoint customization                                             |\n| Security      | Using some security configs                                                                        | Yes - please refer to the [Arks configuration files](#arks-configuration-files) below |\n| Middlewares   | Using some middlewares configs                                                                     | Yes - please refer to the [Arks configuration files](#arks-configuration-files) below |\n| GraphQL Proxy | Proxying the given GraphQL Endpoint                                                                | No                                                                                    |\n\nExposed routes:\n| Name      | Description                                                                             |\n| --------- | --------------------------------------------------------------------------------------- |\n| /metrics  | Metrics route collection                                                                |\n| /liveness | Liveness route                                                                          |\n| /graphql  | GraphQL endpoint                                                                        |\n| /public   | Endpoint for serving static content                                                     |\n| /build    | Endpoint for serving the built client JavaScript bundle React application as production |\n| /         | Endpoint for serving the server side rendered React Application                         |\n\n## Arks Apollo client\nInto an Arks project an Arks Apollo client is created for client side rendering and server side rendering.\u003cbr /\u003e\nFor 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.\u003cbr /\u003e\nSo your GraphQL endpoint is always protected and never exposed into the web browser.\n\nIt 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.\n\n## Arks React application\nInto an Akrs project, the Arks React application is made to simple to use and to implement.\u003cbr /\u003e\nInto 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!\n\n```tsx\nimport * as React from 'react';\nimport { Switch, Route } from 'react-router-dom';\n\nimport { \n    Home,\n    Help,\n    NotFound,\n} from './pages';\n\nexport default function App(): React.ReactElement {\n    return (\n        \u003cSwitch\u003e\n            \u003cRoute exact path='/'\u003e\n                \u003cHome /\u003e\n            \u003c/Route\u003e\n            \u003cRoute path='/help'\u003e\n                \u003cHelp /\u003e\n            \u003c/Route\u003e\n            \u003cRoute path='*'\u003e\n                \u003cNotFound /\u003e\n            \u003c/Route\u003e\n        \u003c/Switch\u003e\n    );\n}\n```\n\nAs you can understand this is **mandatory file**!\u003cbr /\u003e\nPage components are under the *src/pages/* directory.\n\nIn the future the Arks React application will be shape with more sturucted directories and files!\n\n## Design systems and stylesheets\nFor now the Arks webpack compiler is not made to support stylesheets compilation, this feature will come maybe in the future.\u003cbr /\u003e\nArks 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](https://chakra-ui.com/).\u003cbr /\u003e\nSoon Arks will provide an official support for design systems with samples.\n\n## Samples\nYou can find a bunch of samples in the [samples](./samples) directory of the project.\u003cbr /\u003e\n\n## Known Bugs\nHere is the list of known bugs of Arks :\n\n| Name                            | Description                                                 | Corrected    |\n| ------------------------------- | ----------------------------------------------------------- | -----------: |\n| React hot loader not detected   | False/true - Present and functionnal but not detected       | No           |\n| SSR Matching                    | After webpack compliation for SSR React trees doesn't match | No           |\n\n## Built with\n\n* [TypeScript](https://www.typescriptlang.org/)\n* [React](https://reactjs.org/)\n* [React Router](https://reacttraining.com/react-router/web/guides/quick-start)\n* [Apollo GraphQL](https://www.apollographql.com/)\n* [Webpack](https://webpack.js.org/)\n* [Express](http://expressjs.com/)\n* [NodeJS](https://nodejs.org/en/)\n* [Prometheus](https://prometheus.io/)\n* [Commander](https://github.com/tj/commander.js)\n* [Angular DevKit](https://github.com/angular/angular-cli/tree/master/packages/angular_devkit)\n* [Angular DevKit Schematics](https://github.com/angular/angular-cli/tree/master/packages/angular_devkit/schematics)\n* [Gulp](https://gulpjs.com/)\n\n## Authors\n\n* **Aurélien Dupays Dexemple**\n\nThis project is made with ♥ and under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsugardarius%2Farks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsugardarius%2Farks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsugardarius%2Farks/lists"}