dwolfgram / offblocks-admin

OffBlocks coding challenge

OffBlocks Admin Dashboard

A dashboard to view a list of transactions and transaction details. APIs including sign up are mocked in /src/mocks. I chose to use react-query to handle data fetching / caching / retrying due to ease of use and the large amount of features it offers. Jotai atoms for global state such as auth information. Zod is used for type validation.

Testing Steps:

• Sign up with email and password (this will be stored so you can login again with it)
• View list of transactions and use pagination
• Click transaction to see transaction detail modal
• Light and dark themes provided

Mock data & apis live in src/mocks. Querying / endpoints are in src/api.

The API is built to be able to pull lists of transactions by accounts where ideally only the necessary fields to show them in a table are returned. Then, when a user clicks into the modal it can load the whole object. React-query makes it really easy to set how long the data is considered fresh for and so data that won't change can be cached for a long time.

Installation

• Install nvm (Node version manager)
• Install Node v20 and upgrade npm

  nvm install 20
  nvm use 20
  npm upgrade -g npm

• Clone this repository

  git clone https://github.com/dwolfgram/offblocks-admin.git

• Install project dependencies

  npm i

• Edit the .env file

Usage

Start the app locally

npm start

Vite will run web server in the development mode at http://localhost:3000.

This project includes Mock Service Worker to mock API. It starts automatically and provides API for authentication and user functionality.

Building for Production

Build the app for production

npm run build

The app is then ready to be deployed from the /dist folder. See the Building for Production and Deploying a Static Site for more information.

Analysing & Visualizing production JS bundle

There are 2 different tools to analyze and visualize the production JS bundle:

• source-map-explorer

  npm run analyze

• rollup-plugin-visualizer

  npm run visualize

Testing

Launch the test runner in the interactive watch mode

npm run test

Vitest also provides a neat UI to view and interact with the tests. Open it by running npm run test:ui.

See Vitest docs for more information.

Prettier

This project uses Prettier, an opinionated code formatter, to ensure that the whole codebase conforms to a consistent style.

Prettier runs when:

• developer manually executes npm run format command
• in IDE on file-save if configured (VSCode, IntelliJ IDEA)
• automatically on pre-commit hook, right before code is committed
• during CI

ESLint

Project comes with ESLint configured. It helps us prevent common errors.

Code quality concerns, best practices, possible logical issues etc. are checked by ESLint. Our custom ESLint configuration .eslintrc.cjs includes these rules and plugins:

ESLint runs when:

• developer manually executes npm run lint command
• developer starts Vite dev server by npm start command
• in IDE on background if supported (VSCode, IntelliJ IDEA)
• automatically on pre-commit hook, right before code is committed
  • defining actions (.husky/pre-commit) for git hooks is enabled by Husky
  • linting only the files and changes being committed enables lint-staged
• during continuous integration defined in .github/workflows/test.yml

i18n

Running npm run i18n will first parse the whole codebase to find all used i18n keys. Then it inserts missing keys into the JSON files and removes deprecated keys which are not used in the codebase anymore. The result will be an alphabetically sorted JSONs containing all the currently used i18n keys in the codebase.

CI/CD

This project is using GitHub's Actions to run integration tests on each PR and Main branch. It includes running eslint, prettier, tests and building the app. PR becomes mergable only if it passes. We also show badge on top of README.md to show Main branch status.

There is also a code-quality action to run Github's CodeQL analysis.

If you don't use GitHub you can remove the .github folder, otherwise follow these steps to configure your GitHub repository:

1. Go to Settings -> Branches -> Add rule
   • Apply to your master branch
   • Require status checks to pass before merging
   • Select build checks being run in test.yml

What's Included

• React - library to build user interfaces
• Tailwind CSS - utility-first CSS framework
  • tailwindcss-animate - Tailwind plugin for creating animations
  • tailwind-merge - merge Tailwind classes without conflicts
  • clsx - utility to construct classNames conditionally
  • cva - utility to create style variants
• Radix UI - low-level UI component library with a focus on a11y
  • shadcn/ui - collection of designed components mostly based on Radix UI with focus on a11y
• lucide icons - icons set
• Postcss
  • postcss-nesting - supports nesting CSS, following the CSS Nesting specification
  • autoprefixer - parse CSS and add vendor prefixes to rules by (caniuse.com)[https://caniuse.com/]
• Theme Provider - supports Light, Dark and System themes
• TanStack Query - asynchronous state management with declarative, always-up-to-date auto-managed queries and mutations
• Zod - TypeScript-first schema validation with static type inference
• Fetch based API client
  • zod-fetch - to make API client type-safe
• i18next - internationalization framework
  • i18next-browser-languagedetector - language detection plugin
  • i18next-parser - parses the code, extracts translation keys and produces i18n resource file
• Jotai - state management library
• React Router - declarative routing
• react-error-boundary - simple reusable React error boundary component
• JWT Authentication - including all the common features such as Sign-up, Sign-in, Sign-out, Reset password, Email confirmation
• TypeScript - typed superset of JavaScript
  • @tsconfig/bases - strictest & Vite-React
  • ts-reset - a 'CSS reset' for TypeScript, improving types for common JavaScript API's
• Vite - next generation frontend tooling
  • React SWC plugin - speed up Vite dev server with SWC
  • SVG plugin - transform SVGs into React components
  • TypeScript & ESLint check plugin
  • TSConfig paths plugin - support for TypeScript's path mapping in Vite
  • Validate ENV vars plugin
• Vitest - blazing fast Vite-native unit test framework
  • Testing Library - simple and complete testing utilities that encourage good testing practices
    • user-event - simulates user interactions
    • jest-dom - provides custom DOM element matchers
  • jsdom-testing-mocks - a set of tools for emulating browser behavior in jsdom environment
  • MSW - API mocking library for browser and Node.js
    • @mswjs/data - data modeling and relation library for testing
• Prettier - opinionated code formatter
  • package.json plugin - to sort the keys of a package.json file
  • TW plugin - to sort Tailwind classes
• ESLint - pluggable linting utility
• Husky & lint-staged - run ESLint & Prettier before commiting new code
• CI/CD - Github Actions to run integration tests on each PR & Main branch
• source-map-explorer - analyze and debug space usage through source maps
• rollup-plugin-visualizer - visualize and analyze the production bundle