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:

• TypeScript
• CSS Modules + PostCSS

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.