Skip to content

Latest commit

 

History

History
181 lines (135 loc) · 4.93 KB

README.md

File metadata and controls

181 lines (135 loc) · 4.93 KB
Raw

Logbook Web App

Getting Started

Requirements

  • Node.js 12.22 or above

Installation

npm install

Run local development server

npm run dev

Architecture

Logbook is a decentralized static website, without SSR (server-side rendering).

Tech Stack

We use React framework Next.js for the frontend development, with some out-of-box features:

Recommended Libraries:

  • Formik: form components
  • SVGR: SVG icon components

Data Fetching

  • The Graph: indexing service to query on-chan application data
    • Logbook List
    • Logbook Details
    • ...
  • Infura/Alchemy: provider to interact with on-chain data/contracts
    • Transfer Logbook
    • Publish a log
    • Read wallet balance
    • Resolve wallet ENS name
    • ...

File Structure

src
├── components # all reusable components
│   ├── Button # component files in one folder
│   │   ├── styles.module.css # isolated styles
│   │   └── index.tsx
│   ├── Dialog
│   │   ├── Header # sub-components can be nesting
│   │   │   └── index.tsx
│   │   └── index.tsx
│   ├── Head
│   │   └── index.tsx
│   ├── Icon
│   │   └── index.tsx
│   ├── LogbookCard
│   │   └── index.tsx
│   └── index.tsx
├── enums # enums and contants
│   └── index.tsx
├── utils # global utilities
│   └── index.tsx
├── pages # all pages, import from `views` to avoid page components being compiled as pages
│   ├── _app.tsx
│   ├── _document.tsx
│   ├── index.tsx # homepage
│   └── logbook.tsx # logbook detail page
├── styles # global styles, imported in `_app.tsx`
│   ├── base.css
│   ├── reset.css
│   └── variables
│       ├── breakpoints.css
│       ├── colors.css
│       ├── spacing.css
│       └── typography.css
└── views # de facto page components used by `pages`
    ├── Homepage
    │   ├── index.tsx
    │   └── styles.module.css
    └── Logbook
        └── index.tsx

Routing

  • Homepage: /
  • Library: /library
  • Bookcase: /bookcase?address=ADDRESS
  • Logbook: /logbook?id=TOKEN_ID

Design System

The foundation of Logbook Deisgn System is consisted of:

  • Color
  • Typography
  • Layout
  • Interaction
  • Components

Responsive Principles:

  • Mobile-First: write mobile-first styles, and use media queries to scale up to desktop
  • Relative Units: use rem instead of px
  • DRY: Using CSS variables to reduce your code (selectors, properties and media queries)
  • Pure CSS: use CSS to style your responsive components, not JavaScript
  • Vector Images: use SVG as icons

Collaboration

Environments

  • Development: main branch, .env.production
  • Production: develop branch, .env.development

Gitflow

The default branch of Logbook Repository is develop. To start develop new feature, you should fork this branch as your local branch and create a Pull Request to the develop branch. After the PR is merged, the GitHub Actions will automatically deploy your changes to development environment.

Naming Conventions

JavaScript

// TypeScript type & enum
export type PascalCaseType {}
export enum PascalCaseEnum {}

// constants
export const CONSTANT_CASE = {}

CSS

/* kebab-case for variables and mixins */
:root {
  --color-primary: #b32d55;
}

/* camelCase for component in CSS Modules */
.authButton {
  ...;
}

Filename

├── utils
│   └── api.ts # camelCase for non-component files
└── components
    └── AuthButton # PascalCase for component files

UI Components

Based on Design System, UI components should follow the following principles:

  • Atomic: the most basic UI components (<Button>, <Icon>) can't be broken down further
  • Reusable: more complex components (<LogbookCard>) should be composed of other components
  • Stateless: UI components stay in pure UI as functional components

Testing && Deployment

We use GitHub Actions for the CI/CD pipeline.

  • Testing: .github/workflows/test.yml:
  • Deployment: .github/workflows/deploy.yml:

Besides, Husky will run linting before you commit the code.