Julian's Web Garden

Building blocks for making progressive and future-proof websites. Components collection features Astro, HTML, SCSS, JS, TS… Configurations features ESLint, Prettier, Stylelint…

Web garden

🚀  Julian's Web Garden

Astro SCSS TypeScript
ISC License Conventional Commits PRs Welcome
Prettier EditorConfig ESLint Stylelint

Here lies some re-usable components and tooling settings, taking advantage of Astro strengths as much as possible.

Focus is on common web patterns and progressive enhancements.

🤷🏼‍♂️  Philosophy

We've all been to the point of throwing valuable code when adopting new shiny website frameworks.
Thanks to "island architecture" practices, we can establish standard and future-proof, commonly used, generic patterns, using the web holy trinity of languages : HTML / CSS and JavaScript.
That way, we can sprinkle advanced JS widgets as we like, with trendy UI framework, while things like global application utilities remain stable over time.

Vanilla means future-proofing our code, but it also bring the benefit of minuscule file sizes compared to "all-or-nothing" UI frameworks.

🔗  Quick links

LIVE DEMO  🎭  DOCUMENTATION WEBSITE ⎋

Live demo website

Production deployed on code.juliancataldo.com.
Mirror deployed on web-garden.netlify.app. See Production GitHub workflow

Develop deployed on develop--web-garden.netlify.app.
See Branch GitHub workflow

Deployed on Netlify via GitHub actions.

Architecture

Components
Layouts
'Default'
...
Application
'SEO'
'Prefetch'
...
Modules
'Landing'
'SinglePackage'
...
Generic
'Link'
'LicensesReport'
...
Pages
Home
...
Data

Terminology

  • Pages: the base component entry point.
    All other parts (layouts, generic components, modules…) and data are directly or indirectly gathered from here.
  • Layout: Where your website shells lives. This is where you put your global navigation, footer… Alternative layouts can be created like
    Print, Compact, Bare, Blog…
  • App-level component: used everywhere, anytime, for a given layout, which import them.
    E.g. Color modes handler, breakpoints handler…
  • Component: Ubiquitous general purpose, atomic components.
    E.g. icons, images, links, maps, videos…
  • Module: Complex set of components, forming a single purpose page view/section.
    E.g. Landing, SinglePackage, ContactForm…
  • Data: Local JSONs, Markdown files, remote APIs…
    Should be fetched from pages. Note that this is not a hard rule or a technical limitation with Astro as with other frameworks.
    Ultimately, this pattern makes data-flow easier to follow ("top -> down"), preventing spaghetti code, duplications and performance hogs.

📖  Website source code

See default layout and home page for live implementation examples.

📦  Application-level components

These are global components which enhance or augment browser behavior and style, while providing useful utilities to developers, website-wide.

app/
├── BaseDocument/
├── Breakpoints/
├── ColorMode/
├── GoogleAnalytics/
├── HoverPrefetch/
├── Lightbox/
├── Navigation/
├── PageTransition/
├── Resets/
├── ScrollObserver/
├── SEOMetadata/
└── Tooltips/

📦  Components

Generic extendables components.

components/
├── CodeEditor/
├── Diagram/
├── GeoMap/
├── LicensesReport/
├── Link/
├── Tabs/
├── TerminalPlayer/
└── Testbed/

🛠  Tooling configurations

A useful collection for web developers.
Features ESLint, Prettier, Stylelint, Commitlint…
For Astro, React, Vue, SCSS, TS…

configs/
├── vscode/
├── .editorconfig-example
├── commitlint-base.ts
├── eslint-all.cjs
├── eslint-astro.cjs
├── eslint-js.cjs
├── eslint-jsx.cjs
├── eslint-mdx.cjs
├── eslint-ts.cjs
├── eslint-tsx.cjs
├── eslint-vue.cjs
├── index.mjs
├── prettier-astro.cjs
├── prettier-base.cjs
└── stylelint-all.cjs

🚧  To dos

  • Find a way to launch only necessary tests when versioning
  • Implement dev / prod mode for debugging outputs
  • Evaluate PNPM workspaces + tools for replacing Lerna version/publish?
  • Fix Lerna conventional commits not following breaking changes for versioning
  • Full no JS compatibility / fallbacks checks
    • Fix CSS theme not loading
  • Fix flash of unstyled text (critical font loading strategy)

🧑‍🚀  Development

🏁  Commands

# Clone mono-repository
git clone https://github.com/JulianCataldo/web-garden

# Scripts located in root ./package.json

# Bootstrap all packages dependencies
pnpm install --recursive

# Launch implementations demo website
pnpm run demo

# Cypress: Open dev GUI
pnpm run cypress:open

# Cypress: Run test suite
pnpm run cypress:run

# Linkinator: Run links checker with report
pnpm run test:links

# Pre-release, does:
# 1. Packages bump based on commits
# 2. Tagging releases
# 3. Git push
pnpm run version

# Release updated packages on NPM public registry
pnpm run release

Other projects:

🔗  JulianCataldo.com