Skip to content

TECHNICAL_REFERENCES.md

Latest commit

 

History

History
85 lines (61 loc) · 3.76 KB

TECHNICAL_REFERENCES.md

File metadata and controls

85 lines (61 loc) · 3.76 KB

Technical References

Note

Last updated on 2025-07-25

This document outlines the key technical aspects of the sveltevietnam.dev project.

Philosophy

Each technical decision is to be made with considerations of the following:

  1. Minimalism: keep the system simple and easy to understand with only necessary components, modules, and abstraction layers.
  2. Scalability: avoid potential technical debts; make good trade-off between consistency and flexibility. Avoid premature abstraction and predicting the future.
  3. Developer Experience: use innovative and mature technologies, reduce development friction, write self-documented code. Focus on delivering value over over-engineering infrastructure.
  4. Performance: deliver solutions that enable good end-user experience. Prefer functionality over decoration.

Technical Stack

This section lists the current technical stack for the project. The stack is subject to change as the project evolves. Discussions are welcome.

Infrastructure & Base Framework

  • cloudflare: domain hosting, infrastructor provider for both frontend, backend, and database (D1)
  • pnpm: package manager, alternative to npm
  • turborepo: manage dependencies between projects in the monorepo
  • vite: build tool & development server
  • svelte-kit: fullstack metaframework

Development Tooling & Workflow

Backend Specifics

  • wrangler: local development CLI for cloudflare services (pages, workers, D1, ...)

Frontend Specifics

  • svelte: the frontend framework (think react or vue)
  • postcss: CSS preprocessor (think Sass but more plugin-based & JS-friendly)
  • tailwindcss: utility-first CSS framework (think Bootstrap but more performant & customizable)
  • animejs: complex animation

Other transition, state management, routing solutions are provided first-party by svelte & svelte-kit.

Testing

We use Vitest and Playwright for testing.

Typescript or Javascript?

Important

Prefer JS (preferably with JSDocs) for libraries and scripts, and TS for sites and applications.

Sites (sites/... in our case) typically already have a build step or at least some preprocessing before the dev server can serve modules to clients. TS in these cases provides good developer experience without much tradeoff. In libraries or shared packages, however, having TS will introduce complexity and friction to the development workflow because we would lose direct access to the source code and have to rely on dependencies around build & workflow setup. JS with JSDocs is usually sufficient.

Where to Start?

Follow instructions from DEVELOPMENT to get started.
⚡