How monoharada/simple-jsx-ssg works
Main Components
• Source Layer – This consists of the core application code:
• src/ directory: Contains assets (CSS, images, JS), components (UI elements like Header, Card, etc.), frame (Frame.tsx, Head.tsx, Layout.tsx), pages (the actual JSX pages), and data (page_metadata and image details).
• site_setting.ts and types.d.ts set up global settings and type definitions.
• Build/Compiler/Dev Tools Layer – Managed under tools/:
• tools/build: Scripts for HTML compilation, image conversion (from png/jpg to avif), preview server, and production/staging builds.
• tools/compiler: Contains separate compilers/transpilers (css-compile.ts, jsx-dev-runtime.ts, jsx-runtime.ts) that process JSX files into static HTML.
• tools/dev & tools/utils: Support local development with dev servers (bunserver.ts, dev.sh, watcher.ts) and utility scripts.
• Linting/Quality Assurance – Under lint-tools/:
• Contains configurations (.ls-lint.yml, .stylelintrc.json, etc.) and a linting script (linting.ts) for ensuring code/style quality.
• Functions/Middleware Layer:
• The functions/ directory (including _middleware.js) indicates support for server-side functions, middleware processing, or APIs that might be used locally or even in deployment scenarios.
• Public Assets/Deployment Output:
• public/ directory likely holds files served as static assets.
Relationships and Data Flow
• During development, changes in the src/ directory (primarily JSX/TSX files and CSS) are detected by the watcher under tools/dev, triggering the build pipeline in tools/build.
• The build process (using tools/compiler) converts the JSX templates into static HTML and outputs to a directory such as dist/www. The output is then monitored (possibly by a live-reload mechanism) to update the browser automatically.
• Static assets (CSS and images) are organized under src/assets, where CSS files are split into layered cascade files (reset, tokens, base, etc.) and are processed through postcss-import. The CSS layering approach (configured via site_setting.ts) should be highlighted.
• The functions layer (functions/) may handle middleware or backend-like behavior (for example, handling SSI or Cloudflare adaptations) and interacts with the build/server environment.
• Lint-tools provide static analysis both for code (TypeScript, JSX) and markup (HTML/CSS) to ensure a consistent style and quality throughout the development lifecycle.
Architectural Patterns & Technology Choices
• Separation of Concerns: Notice the clear separation between the source code (frontend components, pages, and assets) and the build/compilation tools.
• Compile-Time Transformation: The use of JSX solely as a template engine that transforms into static HTML, ensuring a rapid build process with immediate browser reloading.
• “SRC (Components, Pages, Data)” – a central block.
• “Assets (CSS, Images, JS)” – inside the src folder, highlight sublayers or cascading layers.
• “Build & Compiler Tools” – grouping tools/build, tools/compiler, and tools/dev.
• “Linting & QA” – block for lint-tools.
• “Middleware / Functions” – block from the functions/ directory.
• “Static Output (dist/www)” – show the result of the build process that is served to users.
• Source code (rectangles)
Capturing Essential Architectural Elements
• “Compiler & Build Pipeline”: Show how tools in the “tools” directory intercept, process, and compile source files.
• CSS layering policy as a side note in the assets region to remind developers about the cascade layers order defined in site_setting.ts.
• Integration points with external services (for example, handling SSI, Cloudflare deployment hints, etc.) as per the README’s directions.
Happy diagramming!