{"id":19150450,"url":"https://github.com/vicompany/front-end-guidelines","last_synced_at":"2026-03-19T08:22:51.993Z","repository":{"id":43205400,"uuid":"73360489","full_name":"vicompany/Front-end-Guidelines","owner":"vicompany","description":"Our Front-end documentation","archived":false,"fork":false,"pushed_at":"2021-11-09T12:24:55.000Z","size":84,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-01-03T18:15:26.687Z","etag":null,"topics":["coding-standards","evergreen-browsers","front-end","sass-guidelines"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vicompany.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-10T08:13:14.000Z","updated_at":"2022-07-13T12:23:22.000Z","dependencies_parsed_at":"2022-09-11T18:03:45.943Z","dependency_job_id":null,"html_url":"https://github.com/vicompany/Front-end-Guidelines","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicompany%2FFront-end-Guidelines","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicompany%2FFront-end-Guidelines/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicompany%2FFront-end-Guidelines/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicompany%2FFront-end-Guidelines/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vicompany","download_url":"https://codeload.github.com/vicompany/Front-end-Guidelines/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240236198,"owners_count":19769571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coding-standards","evergreen-browsers","front-end","sass-guidelines"],"created_at":"2024-11-09T08:12:04.105Z","updated_at":"2026-03-03T04:11:28.486Z","avatar_url":"https://github.com/vicompany.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Front-end at VI Company: Web Standards First\n\nThis document defines the core standards for front-end development, prioritizing performance, maintainability, and strict adherence to modern web specifications.\n\n## I. Core Architectural Principle: HTML-First and Progressive Enhancement\n\nOur 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.\n\n### Standards\n\n- **Static Baseline:** All pages must be fully functional and readable with JavaScript disabled.\n- **Island Architecture:** We implement the Island Architecture pattern, where all client-side logic is confined to small, independently hydrated, and self-contained units (islands).\n- **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.\n\n## II. Interactivity and Encapsulation Tiers\n\nClient-side interaction is introduced via a tiered dependency model. We prioritize native browser capabilities and encapsulation standards over monolithic frameworks.\n\n| **Tier**   | **Purpose**                                                                                             | **Primary Technology**                               | **Standard Utilized**                |\n| ---------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------ |\n| **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 |\n| **Tier 2** | High-fidelity, reactive, and state-intensive experiences (e.g., trading grids, real-time data binding). | **Stateful UI Framework (Vue)**                      | Framework-Specific Reactivity        |\n\n### Standards\n\n- **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.\n- **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).\n\n## III. Modularity and Code Organization (Monorepo)\n\nA **Monorepo** structure is mandatory for promoting code sharing, managing dependencies, and establishing clear contract boundaries.\n\n### Structure\n\n- **Applications (/apps/my-app):** The primary rendering layer (Astro pages/layouts) which **consumes** shared packages.\n- **Component Library (/packages/components):** Houses all reusable interface elements.\n- **Utilities \u0026 API (/packages/utils):** Contains loggers, formatters, API client wrappers, etc.\n- **Types (/packages/types):** Contains shared types and TypeScript definitions.\n\n### Standards\n\n- **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.\n- **Clear Ownership:** Any component logic that is not tied to the main application's routing or layout must reside within a package.\n\n## IV. Data Handling and Asynchronous Integrity\n\nThe 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.\n\n### Standards\n\n- **API Client Integrity:** All network communication must be abstracted behind client wrappers in packages/utils to centralize request handling, error normalization, and logging.\n- **Non-Blocking User Experience:** The UI must never block or wait synchronously for long backend processes (e.g., bulk report generation).\n  - Initiate the long-running process and confirm acceptance immediately.\n  - Implement web sockets or server-sent events to update the user on the job's completion status.\n\n## V. Error Management and Resilience\n\nFrontend code must exhibit resilience by treating expected failure scenarios as part of the normal program flow, reserving exceptions for catastrophic failures.\n\n### Standards\n\n- **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.\n- **Exceptional Situations (Catastrophic Failures):** Use JavaScript exceptions only for unrecoverable faults (e.g., network disconnects, unhandled API errors, environment misconfiguration).\n- **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.\n\n## VI. Other sources\n\n- **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.\n- **Front-end Boilerplate:** Check out our internally hosted Boilerplate containing our latest setup.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicompany%2Ffront-end-guidelines","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvicompany%2Ffront-end-guidelines","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicompany%2Ffront-end-guidelines/lists"}