CommonsPub is a multifunctional federated network that allows communities to coordinate a wide range of needs together and connect to other like-minded communities.
Over the last year we worked hard to define a streamlined and productive development process to code, customize and evolve the user interface (UI) of this open federated network.
Our vision was to achieve modularity through simplicity, an old and ongoing quest, even more important when the product should reflect not only the company brand, ethics and goals, but also be flexible enough to satisfy diverse needs. After all, each instance on the federated networks might be run by people with different goals and values.
As open source software is becoming more and more prominent over the web, we have to deal also with wider issues:
- How does the design of open source software help shape communities?
- How do communities shape the open source software?
- How can this symbiosis can empower both parties? (rather than slowly bind them to an unproductive and frustrating relationship)
The following is a technical documentation to describe how we developed the CommonsPub front-end codebase to accomplish such challenges and a way to encourage designers, developers and instance admins to contribute with ideas and codes to such vision.
git clone https://gitlab.com/CommonsPub/Client.git commonspub
cd commonspub
yarn
cp .env.example .env
The CommonsPub client connects to a graphql endpoint to perform queries and mutation over the database.
In order to launch locally the client, you’ll need a running backend. Here you will find a detailed documentation about how to run the CommonsPub backend locally (manually or with docker).
Once you’ve got a backend up and running on http://localhost:4000, you can move further running the client.
(nd. If you just want to run storybook, there is no need to install and run any backend, as stories are populated with fake data)
Note that if you run the client and the server on the same machine with default settings, the GraphQL server will be listening on port 4004. The environment variable REACT_APP_GRAPHQL_ENDPOINT should be then changed to http://localhost:4004/api/graphql in .env.
You will be able to access the Apollo GraphQL Playground at the same address in the browser.
We use linguijs to provide multi-languages. Before launching the app, make sure you’ve added one or more translations to the app.
Currently CommonsPub is translated in the following languages:
en_GB: 'English, British',
en_US: 'English, USA',
es_MX: 'Español, Méjico',
es_ES: 'Español, España',
fr_FR: 'Français, France',
eu: 'Euskara',
ar_SA: 'العربية, المملكة العربية السعودية'
Apart from en_GB that is the default language, feel free do add the needed translations for your scope, when launching the script:
yarn add-locale en_GB en_US es_MX es_ES fr_FR eu ar_SA
yarn start
Visit http://localhost:4000 🌱
A storybook is available to document the different UI components and their use cases. You can run it with:
yarn storybook
Visit http://localhost:5000 🍄
(Describe the main libraries we use, and how they are related to each others)
Our main dependencies are:
- Typescript - a strict syntactical superset of JavaScript
- React - a JavaScript library for building user interfaces
- Apollo - a complete state management library for JavaScript apps
- Rebass - react primitive UI components built with styled-system
- Styled-components - styled-components allows you to write actual CSS code to style your components
- Storybook - It makes building stunning UIs organized and efficient
- Lingui - A readable, automated, and optimized (5 kb) internationalization for JavaScript
(Describe our internal flow when dealing with a new feature: how we design the related module and implement the needed business logic to hook it to the Back end)
(Describe in which ways and terms a community can adapt CommonsPub FE to their own requirement)