https://github.com/vicompany/front-end-guidelines
Our Front-end documentation
https://github.com/vicompany/front-end-guidelines
coding-standards evergreen-browsers front-end sass-guidelines
Last synced: 21 days ago
JSON representation
Our Front-end documentation
- Host: GitHub
- URL: https://github.com/vicompany/front-end-guidelines
- Owner: vicompany
- License: mit
- Created: 2016-11-10T08:13:14.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2021-11-09T12:24:55.000Z (over 4 years ago)
- Last Synced: 2025-01-03T18:15:26.687Z (over 1 year ago)
- Topics: coding-standards, evergreen-browsers, front-end, sass-guidelines
- Size: 82 KB
- Stars: 3
- Watchers: 6
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Front-end at VI Company: Web Standards First
This document defines the core standards for front-end development, prioritizing performance, maintainability, and strict adherence to modern web specifications.
## I. Core Architectural Principle: HTML-First and Progressive Enhancement
Our primary goal is to deliver a robust, functional experience using minimal network resources. This is achieved by adhering to an **HTML-First** methodology, where client-side JavaScript is treated strictly as an enhancement.
### Standards
- **Static Baseline:** All pages must be fully functional and readable with JavaScript disabled.
- **Island Architecture:** We implement the Island Architecture pattern, where all client-side logic is confined to small, independently hydrated, and self-contained units (islands).
- **Minimal Payload:** JavaScript is only shipped to the client when the component explicitly requires interactivity. This strategy is managed via the **Astro** framework, which enforces server-side rendering by default and orchestrates selective client hydration.
## II. Interactivity and Encapsulation Tiers
Client-side interaction is introduced via a tiered dependency model. We prioritize native browser capabilities and encapsulation standards over monolithic frameworks.
| **Tier** | **Purpose** | **Primary Technology** | **Standard Utilized** |
| ---------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------ |
| **Tier 1** | Simple DOM manipulation, event listeners, observers (e.g., menu toggle, carousel manual slide). | **Native Browser APIs (Vanilla JS), Web Components** | DOM API, ES Modules, Custom Elements |
| **Tier 2** | High-fidelity, reactive, and state-intensive experiences (e.g., trading grids, real-time data binding). | **Stateful UI Framework (Vue)** | Framework-Specific Reactivity |
### Standards
- **Tier 1 Preference:** Simple [HTML Web Components](https://blog.jim-nielsen.com/2023/html-web-components/) (using the light DOM instead of Shadow DOM) are the preferred mechanism for simple UI interactions. They offer automatic instantiation and life-cycle methods and a container for scoped JavaScript functionality while maintaining global CSS styling.
- **Tier 2 Restriction:** Stateful frameworks (Tier 2) must be reserved only for areas where cross-component reactivity is complex and unavoidable. Hydration must be lazy (e.g., only when visible or idle).
## III. Modularity and Code Organization (Monorepo)
A **Monorepo** structure is mandatory for promoting code sharing, managing dependencies, and establishing clear contract boundaries.
### Structure
- **Applications (/apps/my-app):** The primary rendering layer (Astro pages/layouts) which **consumes** shared packages.
- **Component Library (/packages/components):** Houses all reusable interface elements.
- **Utilities & API (/packages/utils):** Contains loggers, formatters, API client wrappers, etc.
- **Types (/packages/types):** Contains shared types and TypeScript definitions.
### Standards
- **Shared Typing:** All data models and API contracts must be defined in the packages/types workspace and imported by both the API wrappers and UI components.
- **Clear Ownership:** Any component logic that is not tied to the main application's routing or layout must reside within a package.
## IV. Data Handling and Asynchronous Integrity
The front-end must handle data consumption and long-running asynchronous tasks in a non-blocking and predictable manner, aligning with the server's transactional model.
### Standards
- **API Client Integrity:** All network communication must be abstracted behind client wrappers in packages/utils to centralize request handling, error normalization, and logging.
- **Non-Blocking User Experience:** The UI must never block or wait synchronously for long backend processes (e.g., bulk report generation).
- Initiate the long-running process and confirm acceptance immediately.
- Implement web sockets or server-sent events to update the user on the job's completion status.
## V. Error Management and Resilience
Frontend code must exhibit resilience by treating expected failure scenarios as part of the normal program flow, reserving exceptions for catastrophic failures.
### Standards
- **Trivial Situations (Expected Failures):** User input validation errors, non-existent records (HTTP 404), or empty search results must be managed via standard return types, not throw/catch.
- **Exceptional Situations (Catastrophic Failures):** Use JavaScript exceptions only for unrecoverable faults (e.g., network disconnects, unhandled API errors, environment misconfiguration).
- **Component Error Boundaries:** Interactive Islands (Tier 2) must implement local error boundaries to prevent catastrophic failure of the entire page due to an isolated component issue.
## VI. Other sources
- **Front-end Tech Radar:** See our [Front-end Tech Radar](https://github.com/vicompany/frontend-techradar) for more information about technologies used now and in the past.
- **Front-end Boilerplate:** Check out our internally hosted Boilerplate containing our latest setup.