Skip to content

Home

Jump to bottom
Khai Hung Luong edited this page Jun 12, 2025 · 32 revisions

Viet Vibe Foundation - Main Web Project

Introduction

Welcome to the Viet Vibe Foundation's main web project repository! This project serves as the official website for our foundation, which is made by a collaborative effort of VVF's dev team. The following instructions will guide you on how to contribute, deploy, and maintain the web project.

Table of Contents

Editors/Media Guide & Other Pages
Developers Guides and Conventions
  1. Getting Started
  2. Contributing to the Project
  3. Deployment Instructions
  4. Project Folders Instructions
  5. Domain and Database Configuration
  6. Extensions
  7. React Coding for Accessibility
  8. Translation and Localization
  9. Image, Font, and CSS Optimization
  10. API
  11. Stripe
  12. Notification - Error handling
  13. Other Sources

Getting Started

To get started with the Viet Vibe Foundation web project, please follow the instructions below:

  1. Clone the Repository:

  • Make sure you clone the repository from the dev branch for development.

  1. Installation:

  • Follow the instructions in the README file for the environment's installation steps.

  1. Environment Variables:

  • Make sure you have the necessary environment variables set up. These can be found in the Env Doc (only accessible to officers with a VVF Gmail account).

Contributing to the Project

To contribute to the project, please follow these steps:

  1. Request Invitation:

  • If you are not yet a contributor, please ask Khai Hung for an invitation to the repository (through Discord dev channel or private message).

  1. Branching Strategy:

  • Always clone the code from the dev branch to a new branch for development.
  • When your work is complete, make a pull request to the dev branch.

  1. Pull Request:

  • Make sure that all checks pass before submitting a pull request.

  • Always check and test your code in the preview of at least one of the builds of Amplify and Vercel (preferably Amplify because we host our main web there).

  • Assign shiro102 as the reviewer for your pull request.

Deployment Instructions

  1. AWS Account:

  1. Vercel:

Project Folders Instructions

The current project has 7 main folders: app, components, lib, locales, prisma, public and hooks.

Below are the functionalities of each folder:

  1. App:

    • Contains all the routings, the layouts and the front-end components of the website.
    • For more info about how the routing works, read here: Next.js Introduction and Guides.

  2. Components:

    • Contains all the reusable components of our website. Currently, we have 2 types: translator and ui components.

      a. Translator:

      b. Ui (Important):

      • All components here are reusable UI components from the shadcn library, which should be utilized instead of normal HTML ones (for example, buttons, forms, inputs, etc.).
      • For button, there are multiple variants that you can choose, please take a look at them and use by following syntax: <Button variant="default">.

      c. Loading Skeleton:

      • These are for displaying placeholder skeleton to the users before the images/text/data are loaded in our front-end.
      • They will be used in loading.tsx, which is placed on the same level as layout.tsx and page.tsx of any path.

  3. Lib:

    • Contains all the customized actions, database queries, utility functions, reusable types, reusable custom CSS classes and Zod schema (for data type validation).
    • Please take a look at all of them, especially ui/css folder to know the existing CSS class and utilize them for more organized and efficient development.

  4. Locale:

  5. Prisma:

    • Contains the Prisma schema of our database and the migrations.

    • If you just start cloning the project or have any problem with the database, run:

      npx prisma migrate

    • Connection Strings: Available in Env Doc.

    • To access the database in local:

    • Run npx prisma studio after ensuring the connection strings are in .env.

    • npx prisma migrate dev to update the db, but only when it does not cause the database's deletion (please check carefully). When run, give a meaningful name for the migration.

    • If you know what field is missing, then manually create a migration and use npx prisma migrate resolve --applied #name.

    • Use npx prisma db push if migrate dev does not work.

  6. Public:

    • Contains all the images or icons we want our website to access locally in the hosting server.
    • IMPORTANT: This folder will only be used for small icons and logos. For normal images please use Google Drive, further instructions read here: Image, Font, and CSS Optimization.

  7. Hooks:

    • Contains all the custom hooks (e.g similar to useState, useEffect).
    • One important hook is useToast, which can be used to display notification to users. Please utilize this hook instead of other notification functions.

Domain and Database Configuration

Database Schema

Link to UML: Click here

Zoho (Domain Configurations)

  1. Account: [email protected] (User role).
  2. Password: Available in Credentials Doc.
  3. Admin Console for admin-level configurations.
  4. Mail Console for email receipt (we will not use Zoho mail as we already have Google Workspace email).

PostgreSQL (Neon Database)

  1. Account: [email protected] (Login via Google).
  2. Password: Available in Credentials Doc.
  3. Connection Strings: Available in Env Doc.
  4. To access the database in local:
    • Run npx prisma studio after ensuring the connection strings are in .env.
  5. To upload db changes, you can use either:
    • npx prisma migrate dev for most of the time, but only when it does not cause the database's deletion (please check carefully). When run, give a meaningful name for the migration.
    • If you know what field is missing, then manually create a migration and use npx prisma migrate resolve --applied name
    • Use npx prisma db push if migrate dev does not work

Extensions

  1. Prettier Formatter (Required):

  • We will use Prettier Formatter for code and CSS formatting to make them consistent.
  • In VS Code, go to Extensions → Search for "Prettier - Code Formatter".
  • Use the shortcut Alt + Shift + F to format the code (Please apply every time you finish developing any component).

  1. Code Spell Checker (Required):

  • A basic spell checker for codes and comments.
  • In VS Code, go to Extensions → Search for "Code Spell Checker".

  1. Tailwind CSS IntelliSense (Required):

  • Extension for autocompleting Tailwind CSS, display CSS info by hovering, etc.
  • In VS Code, go to Extensions → Search for "Tailwind CSS IntelliSense".

  1. Color Highlight:

  • Useful extension to color any string that is RGB hex, helpful when you need to style component using CSS.
  • In VS Code, go to Extensions → Search for "Color Highlight".

  1. Custom CSS Class:

a. CSS Peek: - Allow you to navigate to custom CSS classes (note that CSS custom class will not display info on hover, and please refer to CSS Section for more info on custom CSS classes). - In VS Code, go to Extensions → Search for "CSS Peek".

b. IntelliSense for CSS class names in HTML: - Allow auto-complete custom CSS classes. - In VS Code, go to Extensions → Search for "IntelliSense for CSS class names in HTML".

  1. AI Copilot:

  • Some AI Copilots that are free and integrated in VS Code:
    1. Supermaven (Have inline code suggestion and understand context, can input OpenAI token for 4o model, fast).
    2. Codeium (Have inline code suggestions and understand context, as well as component explanation and refactoring, slow).
    3. GitHub Copilot (Only chat suggestion).
  • If you need OpenAI Token, please use Khai Hung's one here Credentials Doc.
  • Please DO NOT use Copilot excessively and try to understand the code completely.

React Coding for Accessibility

As part of our commitment to accessibility as a non-profit organization to promote inclusivity, please ensure that all components use WAI-ARIA standards whenever possible. Below are some resources and guidelines:

  1. WAI-ARIA Guidelines:

  • Use WAI-ARIA attributes for accessibility in all React components if possible.
  • Usually, we don't need to apply ARIA if the content is self-explained (for example button "Login"). However, if the element cannot be understood without a context or actually seeing (a Google icon that allows login with Google, loading spinner, any icons and their functionalities, etc.), then we have to add ARIA attributes.
  • The most common ARIA attribute is "aria-label", which indicates the ARIA content for the elements. There are also "aria-current" (for indicating current page), "aria-sort" (for sorting table), etc. Please learn more about them and use them accordingly.

  1. Accessibility Resources:

Translation and Localization

i18nexus for Translation Management

Join the Project:

  • Request an invitation to join the VVF-Web project in i18nexus if you don’t have access yet.

Translation Workflow:

a. Embed translations in component:

  • For each new component, add translations by using initTranslation (server) or useTranslation (client) based on the component type.

  • Choose the correct namespaces/workspaces that the translations are located and define the translation key name. Read part b to know how to find the namespaces/workspaces (Note: we can specify more than one namespace/workspace).

    const { t } = await initTranslation(locale, ['homePage', 'common'])
...
<span>{t('content-copyRight')}</span>

  • Translation key name must follow this rule: type-component, where type can be: header, button, description, etc. and component is the one where the translation is in. For example: {t('button-introduction')} is for button in the introduction part (Note: different workspaces/namespaces can have same name, so you have to choose the correct workspaces/namespaces).

  • Use i18nexus app to centralize and manage translation strings. It provides automatic Google Translate to Vietnamese and French from English.

b. Create new translations:

  • Choose correct namespace/workspace. For example, if you want to add a translation for a button in the home page, choose "homePage". If you add a new page/route, you can create a new namespace accordingly (if you don't know if you should create or not, please ask in our Discord chat).

  • Add new English strings in "String Management", the key will be the translation's name we define in part a.

  • If you are Vietnamese, please help confirm the translations in Vietnamese after you create them in "Translator View" (French is optional).

  • Pull the changes locally using i18nexus pull or restart the dev server with yarn dev.

Image, Font, and CSS Optimization

Images

  1. Storage:

    • All images should be stored in this Google Drive folder.

    • Embed images in the code using the format below, where the xxx is the image ID, and sz=w1000 is the image's width which can be changed accordingly. Please note that we will limit the image size to be less than 1000(px) to ensure our web's speed and loading time (high-res images will cause burden when rendering the web).

      https://drive.google.com/thumbnail?id=xxx&sz=w1000

    • To find image ID, go to the Google Drive folder > right-click on image > Open in new tab. The image id will be inside the URL between "/d/" and "/view". For example: https://drive.google.com/file/d/1RcAKxLd76W-Nuu9FdNYlxNDdEDBD6RfU/view -> id is 1RcAKxLd76W-Nuu9FdNYlxNDdEDBD6RfU.

  2. Usage:

    • Always use Image tag from next/image which is the most optimized image tag for Next.js project.
    • Embed the image link in src attribute.
    • Always add alt attribute to the image for accessibility.
    • For main images that have to be in big size such as header background, you can use priority attribute so it can be loaded first and improve our web loading time.
    • For background images, add to the parent div's className relative, and use next-background for the image's className, which is a custom CSS class for background. More examples, please check: app\[locale]\(Home)\_components\_introduction\Introduction.tsx.

  3. For more info and best practices, refer to the following links:

Fonts

  1. Font Usage:

    • Use only fonts from lib/ui/fonts. They are Google font libraries suited for web development.
    • There are two main fonts:
    • We will use them as CSS variables (Please refer to lib/ui/css/header.css for more info).

  2. For more info and best practices, refer to the following links:

CSS

  1. CSS Optimization:

    • Group related font and styling rules together in the CSS (in the folder lib/ui/css).

    • Double check for existing styles before creating new ones to avoid duplication.

    • If you need a new group, please message me in our Discord chat so we can discuss.

  2. Global CSS Variable and Global Tailwind CSS Class:

    • All global CSS variables such as bg colors, text colors, etc. are stored in lib\ui\css\globals.css and tailwind.config.ts

    • In global.css, we define CSS variables that will be used in tailwind.config.ts

    • In tailwind.config.ts, we define global Tailwind CSS classes that can be used everywhere in our code. The syntax will be [TailwindClass]-[mainCategory]-[variant]. For example: bg-bgColor (for default variant) or text-textColor-brand or border-bgColor-brandLight

    • DO NOT use custom color/RGB hex if it can be found in our Global Tailwind CSS Class. This will help our color and design more consistent.

    • CSS and Tailwind Resources:

API

Query Endpoints

  • Always query the GET endpoint in server components in order to protect our endpoint
  • For other endpoints such as POST, PUT, etc. always protect them by checking the user login status and the role accordingly

Stripe

Stripe Documents

Notification and Error handling

Notification Library

  • We are using toast from Sonner library from shadcn/ui to display notifications/errors

Sonner Usage

  • For successful messages:

       const currentDateTime = getCurrentDateTime()
   toast.success('Success', {
     description: (
       <div className="flex flex-col gap-1">
         <span>{response.message}</span>
         <span style={{ color: "var(--muted-foreground)" }}>{currentDateTime}</span>
       </div>
     ),
     style: {
       color: '#22c55e' // green-500 color
     }
   })

  • For unsuccessful messages:

     toast.error('Error', {
   description: (
     <div className="flex flex-col gap-1">
       <span>Something went wrong</span>
       <span style={{ color: "var(--muted-foreground)" }}>{currentDateTime}</span>
     </div>
   ),
   style: {
     color: '#ef4444' // red-500 color
   }
 })

Error handling instructions

  • Return readable and easy-to-understand messages, especially when they are for the users
  • Include the actual errors as well
  • Add colour for user-friendly alerts (e.g., red for errors, yellow for warnings, green for success) to improve clarity and visibility in the UI
  • Ensure technical errors are logged in the console or sent to a monitoring system, while users only see helpful guidance on what to do next
  • Avoid exposing sensitive information or internal server details in user-facing messages

Other sources

Copyright © 2025 Viet Vibe Foundation

Clone this wiki locally