Figma   |   Notion

NeoExpertise is a gaming e-commerce

Table of contents

• Introduction
  • What are we?
  • Core Values
• Development Environment
  • Tools
    • git
    • github-cli (optional)
    • node
    • yarn
    • IDE/Code Editor
• Git Workflow
  • branches
  • commits
  • releases
  • QA
• Architecture
  • monorepo
    • microservices
    • microfrontends
  • technologies
  • tests
  • accessibility
• Figma
  • Style Guide
  • Design System
  • UI Kit
• Notion
• Roadmap
  • Plugins Marketplace
  • Microservices?
  • Own packages?
• Challenges
• License
• Support
• You may also like
• Contributors

📖 Introduction

What are we?

Neo Expertise is an e-commerce for gamers, bringing exclusive and personalized content that only exists here

Core values

We aim to build a product that looks and feels good to use but projected for the gaming niche and having customization be it's biggest feature.

Development Environment

Before diving into how to develop for Neo Expertise, we'll need some gear first, let's get that ready.

Tools

Here is a set of cherry-picked tools and why each is needed

• Git

  you probably know this by now but git is pretty much essential when it comes to building software, you'll need it if you want to make any bigger contributions

• Github CLI* (Optional)

  github cli comes in handy when you need to create and merge multiple branches, in this project it plays a big role

• Node

  Node.js is the biggest technology of all in the repo, because it allows us to run javascript outside of the browser, every library/package/app is build with node.js, you're contributing to any of those, you must install node.js

  as of the version, anything above 12.22.0 will work

  here is worth mentioning NVM, which makes it easy to have multiple node version in the same OS

• Yarn

  Here at Neo Expertise we're using Yarn Berry (v3.1.1) which is the more recent version of Yarn, Yarn berry gives us more flexibility on how to write software but also faster than npm, yarn wrote a whole article on why and how you should migrate

  • Global caching of depencencies
  • Workspaces
  • Offline cache
  • Sharing Dependencies

  All of these features play a HUGE role in how our software is written and also how it's shipped to the end user

  As of now we don't make use of Yarn Berry's PnP, so any contribution that enables it will not be accepted

  
  

  Yarn Workspaces
  This is probably the feature that plays the biggest role of all in our monorepo, since Yarn Workspaces is the underlying system that makes all of this work. With yarn workspaces it's possible to share code & dependencies through multiple projects seamlessly, here's a full explanation on why of that

• IDE/Code Editor* (Optional)

  as far as it goes you could use any code editor or IDE to contribute but if you're looking for some guidance we will recommend you some editors, why you would choose them and what plugins you should have installed to have the best experience while developing

  • Visual Studio Code

    Visual Studio Code (not be mistaken by it's older purple brother, Visual Studio) is easily the most well known and "best" code editor available, our whole team at Neo-Florescence uses it, but we recommend you to use some plugins to enhance your coding experience.

  • LunarVim

    LunarVim is an IDE built on top of the good ol' classic Neovim, looking very similar to Visual Studio Code but being as exensible as Neovim gets

  • Emacs

    Emacs is a text editor that is kind of similar to vim, being very customizable and fast

  Here's a list of plugins you might find useful to have in your Code Editor/IDE

  • EditorConfig
  • Eslint
  • Prettier

Git Workflow

Before contributing to NeoExpertise it's important for you to understand how we like to manage and create stuff in here

Branches

This is a guide of how to manage your branches when contributing to NeoExpertise This guide applies to any kind of contribution, be it a bug fix, feature, typo and etc, this highly increases the codebase security and and reduces incomplete or not tested features to get to the final codebase

• Create an Issue
  First, create an issue describing the changes you want to make to codebase, in the issue specify which service you want to change, why, what you're planning in doing, if our team flags your issue as valid, you can continue on, otherwise, close the issue.

• Create a new Branch
  After your branch is flagged with the tag 'valid' you're free to create a branch to solve the problem you're trying to solve, for this you can use git CLI.

    git branch <BranchName> # Creates the branch
    git checkout <BranchName> # Go to the selected branch
    # ====
    #  OR
    # ====
    git checkout -b <BranchName> # Creates and Goes to the branch

  Now just copy and paste those commands into your terminal and chage the branch name to the name you would like to give to your branch
  

  ^{_{Note that the '<' and '>' should not be in the final script}}

  Commits

After you've created your branch you need to actually change stuff in it so we can verify and merge it to the main branch

A commit is a piece of changed information, may it be code, text, or anything else, those commits, contain a type, a scope and a description like so:

feat(website): add home landing page

It's important that everytime you make a change or fix a bug or add a new feature you commit that, so we have a more organized git timeline

Our teams has already setup a set of tools to help you create better commits, those tools include:

• husky - fires commands before a commit is creates
• lint-staged - run linting tools on the files you've changed
• jest - run tests to ensure everything is working

Don't worry about how to use all of them, they will run automatically after you run

git commit

If some annyoing text editor keeps opening for you, please use:

git commit --no-edit

Using the --no-edit flag on the commit script will prevent git from making any changes to your commit

Releases

we still don't have a release system in place, so our team will launch new releases of the app whenever there is a new feature or a major bug fix

QA - Quality Assurance

here at NeoExpertise we build some guidelines regarding the QA process and how you should test our prototypes, today the prototypes are located in here, you can test them using the guidelines given on notion, whenever you find a problem, you can create a issue here on github

Architecture

After getting your tools ready, let's dive into NeoExpertise's monorepo architecture and how things are planned before they're built

Monorepo

So basically, we've adopted a monorepo architecture, where all of our codebase lives under a single repository and there they share code and dependencies.

• Microservices

  Microservices is the idea of splitting a monolith application into small parts and then put all of those services together under a BFF of Data layer to talk to the front-end, here at NeoExpertise we're still thinking of how to implement this in a way fits our needs and pockets, so still a Work In Progress.

• Microfrontends

  Our team first discovered it at micro-frontends.org and since we've been implementing it in a similar way, of course we can't afford to host 2/4 different apps for each and every occasion but we've recently created a pattern which really helped us develop faster and better. If you want to see the lead up to why we've chosen micro-frontends, there's a pretty long changelog of everything that happened architecture-wise in NeoExpertise down here

  
  

  We've started with two repositories, one repository was the back-end and the other the front-end

  Codebase	Description
  E-commerce	NeoExpertise's back-end repository
  neo-expensive	The front-end, initially build with pure HTML, CSS and Javascript

  
  

  Right after that, things evolved a little bit on the front-end adding a Yarn Workspaces monorepo and some basic "services"

  Codebase	Description
  Lint	All of the repository linting configuration (Eslint and Prettier)
  Desktop	An Electron React App that served as our desktop app
  Next	A Next.js App that would in the future be our official front-end
  Web	Our plain and old web app with HTML, CSS and Javascript

  
  

  After some months and some thinking about the direction we would like to go with this, we've changed out "services" to what would be the "final" version of NeoExpertise.

  Codebase	Description
  Lint	All of the repository linting configuration (Eslint and Prettier)
  Dashboard	A Next.js App that would serve as our dashboard
  Web	Our plain and old web app with HTML, CSS and Javascript

  We dropped the Electron App and Next.js app and stuck with HTML, CSS and Javascript for the final version.
  
  

  Some time after the last codebase update, we ran out of time and couldn't build something we liked, there were many and many merge conflicts here and there, we couldn't works as a team beacuse of the architecture and that limited us to 1 person developing the whole front-end.
  
  So we decided to change, now we've fully adopted a micro-frontend architecture to finally develop as a team and ship updates faster to the end user, as of now, this is how our architecture stands.
  
  We've decided to split our services and apps into 3 categories

  • Libs
    The libs folder contains all of the source that is used to build other packages and apps, such as, linting configuration, compilers configurations and etc
    
    

    Folder	Description
    Lint	All of the repository linting configuration (Eslint, Prettier and Stylelint)
    Postcss	Our base PostCSS configuration that new sevices can use

    
    
  • Packages
    Packages can either be building blocks of another packages or apps, these usually make use of some libs.
    
    

    Folder	Description
    Global	Global css configuration but layer-agnostic, written with only SCSS and compiled down to pure CSS, so this can be used in any other web-related project
    Icons	Our icon library, built with React with all cherry-picked icons from our figma file
    Colors	All of our color tokens served in a javascript object for full compatibility with any system
    UI	Here lies the bigest package of all, containing all UI Elements, these are separated by group and built on demand by page

    
    
  • Apps
    Apps are our apps, that's it, not much explaining to do here
    
    

    Folder	Description
    Web	A Next.js app
    Desktop	A Electron React App
    Mobile	An Expo React Native app

    
    

Technologies

Here's a list of technologies that are fundamental to how NeoExpertise is developed and deployed

Tests

Here at NeoExpertise it's very important to have setup in all of our services so we be sure things are working at anytime, so we have jest setup in the root of the repo but also in each and every foler. Fell free to add plugins to jest if you want to or add another testing library if you thing jest is problematic.

Don't stress about code coverage, that metric is not important to us.

Here's a step-by-step tutorial on how to test things:

1. Check if there's a jest.config.js in the root of the folder you're working on, if there isn't a jest config, create an issue and ask for our team to create one or just create it yourself
2. Check if the thing you want to test isn't already tested, look in the __tests__ folder of the project you're working on
3. Make sure to copy other tests before building your own and change stuff in it to test what you want to test

Accessibility

Here at NeoExpertise we care a LOT, and I mean a LOT about accessibility, if you're building any UI elements/componentes, make sure that it's accessible by keyboard, hover effects work and etc

To help us build UI elements we really like to use radix and headlessUI, these come by default with accessibility features and are WAI-ARIA compliant

Figma

It's important for you to understand how our figma file works, since it there that we built all of our components and layouts.

Design System

Our design system contains a whole set of tools, documentation and principles that together have the objective to complete the company's goal. It's composed of Style Guide, Sketch Library, Pattern Library and other building blocks. Here's and example of how it works

“Um sistema de design não é um projeto, é um produto que serve produtos”. Nathan Curtis

Our design can be broken down in 3 parts:

• Atoms - Simple elements, such as colors and font tokens
• Molecules - Groups of combined elements and common resources, such as input fields, textareas, headers and etc.
• Organisms - Templates made of molecules and atoms such as entire web pages or just large sections

Style Guide

It's a subclass in the design chain. A documentation that should describe the design and padronize the style between all components, so in the style guide there should be rules for how big would the fonts be, size of paddings and margins, colors, border radius and etc.

UI Kit

The UI Kit should contain a relative small number of components that are shared between pages in the layout, they help the front-end engineer to faster develop pages in the same "logical" group

Notion

Sprints

If you get into the NeoExpertise team, you will have you tasks listed at the sprints section of Notion
There we will assign you sprints that will have some tasks to be done, they have a starting and ending date.

License

This project is licensed under the MIT License So feel free to do anything you want with it.
see the LICENSE file for details.

Support

If you ever notice any major bug or loophole, or have experienced some problem in our platform, please create a issue here at github so all of our contributors get notificated.

Contributors

@VitorGouveia @Thiago