{"id":23576090,"url":"https://github.com/pvds/mikrouli","last_synced_at":"2026-04-12T17:02:07.814Z","repository":{"id":269535577,"uuid":"780219244","full_name":"pvds/mikrouli","owner":"pvds","description":"Mikrouli website built using SvelteKit 2, Tailwind CSS 4, Contentful (headless CMS) and hosted as an SSG on Github Pages","archived":false,"fork":false,"pushed_at":"2025-05-07T09:47:33.000Z","size":111713,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T10:46:55.883Z","etag":null,"topics":["biome","bun","contentful","ssg","svelte","sveltekit","tailwindcss","vite"],"latest_commit_sha":null,"homepage":"https://mikrouli.nl","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pvds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-04-01T02:13:56.000Z","updated_at":"2025-05-07T09:47:37.000Z","dependencies_parsed_at":"2024-12-24T09:25:19.357Z","dependency_job_id":"a110effd-f4bc-4e85-9a3e-1145b017c7b5","html_url":"https://github.com/pvds/mikrouli","commit_stats":{"total_commits":147,"total_committers":1,"mean_commits":147.0,"dds":0.0,"last_synced_commit":"4cd44854b4a715c1792b97ec1e62a4a6078df87c"},"previous_names":["pvds/mikrouli"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvds%2Fmikrouli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvds%2Fmikrouli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvds%2Fmikrouli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvds%2Fmikrouli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pvds","download_url":"https://codeload.github.com/pvds/mikrouli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254535825,"owners_count":22087399,"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":["biome","bun","contentful","ssg","svelte","sveltekit","tailwindcss","vite"],"created_at":"2024-12-26T21:12:41.147Z","updated_at":"2026-04-12T17:02:07.804Z","avatar_url":"https://github.com/pvds.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mikrouli Development Platform\n\n\u003e Platform for systemic change.\n\nMikrouli leverages a modern web platform, combining performance, scalability,\nand maintainability. It is built using **SvelteKit**, **Tailwind CSS**, and\npowered by **Contentful** as a headless CMS. The platform emphasizes a seamless\ndeveloper experience and user-centric design.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Getting Started](#getting-started)\n- [Scripts](#scripts)\n- [Workflow](#workflow)\n- [Development Principles](#development-principles)\n- [Project Structure](#project-structure)\n- [Troubleshooting](#troubleshooting)\n- [Documentation](#documentation)\n\n---\n\n## Features\n\n### Development Tools\n\n- **[SvelteKit](https://kit.svelte.dev/):** Framework for building modern web\n  applications.\n- **[Bun](https://bun.sh/):** High-performance JavaScript runtime and package\n  manager.\n- **[Vite](https://vitejs.dev/):** High-speed build tool.\n\n### Styling\n\n- **[Tailwind CSS](https://tailwindcss.com/):** Utility-first CSS framework.\n\n### Testing and Quality Assurance\n\n- **[Vitest](https://vitest.dev/):** Unit testing framework.\n- **[Playwright](https://playwright.dev/):** End-to-end testing tool.\n- **[Biome](https://biomejs.dev/):** Linting and formatting.\n- **[Lefthook](https://evilmartians.com/opensource/lefthook):** Git hooks for\n  automated checks.\n\n### Hosting and CMS\n\n- **[GitHub Pages](https://pages.github.com/):** Staging environment host\n- **[Netlify](https://www.netlify.com/):** Production environment host\n- **[Contentful](https://www.contentful.com/):** Headless CMS for managing\n  content.\n\n### Analytics and Monitoring\n\n- **[Umami](https://umami.is/):** Privacy-focused analytics.\n\n### Email\n\n- **[forwardemail](https://forwardemail.net):** Privacy focussed email service\n  provider\n\n---\n\n## Getting Started\n\nIf you already have all dependencies quick start by running\n`bun i \u0026\u0026 bun  start`.\n\n\u003e `bun start` is a shorthand for `bun dev --open \u0026 bun run watch`.\n\n### Prerequisites\n\n\u003e For macOS we recommend using [Homebrew](https://brew.sh/) For Windows we\n\u003e recommend using [Scoop](https://scoop.sh/)\n\n1. **Install Node.js** (v22 or newer):  \n   Follow the [Node.js documentation](https://nodejs.org/).\n    - macOS: `brew install node` or `brew install nvm`\n    - windows: `scoop install nodejs` or use\n      [nvm for windows](https://github.com/coreybutler/nvm-windows)\n\n2. **Install Bun** (v1 or newer):  \n   Follow the [Bun installation guide](https://bun.sh/).\n    - macOS/Linux: `brew install oven-sh/bun/bun` or\n      `curl -fsSL https://bun.sh/install | bash`\n    - windows: `scoop bucket add main` \u0026\u0026 `scoop install bun` or\n      `powershell -c \"irm bun.sh/install.ps1 | iex\"`\n\n3. Install project dependencies:\n    ```bash\n    bun install\n    ```\n4. Set up the project:\n    ```bash\n    bun run util:prepare\n    ```\n\n### Local Development\n\n1. Install dependencies:\n\n    ```bash\n    bun install\n    ```\n\n2. Start the development server:\n\n    ```bash\n    bun start\n    ```\n\n---\n\n## Scripts\n\n- **Workspace**\n\n    ```bash\n    bun run setup\t\t\t\t# Prepare the workspace\n    bun run clean\t\t\t\t# Clean the workspace\n    ```\n\n- **Prepare**\n\n    ```bash\n    bun run prepare\t\t\t\t# Install git hooks with Lefthook\n    bun run sync\t\t\t\t# Creates the tsconfig.json and generated types\n    ```\n\n- **Development**\n\n    ```bash\n    bun run start\t\t\t\t# Start development server and watch for changes\n    bun run start:prod\t\t\t# Build and start production server\n    ```\n\n- **Build**\n\n    ```bash\n    bun run build\t\t\t\t# Build for staging\n    bun run build:prod\t\t\t# Build for production\n    ```\n\n- **Preview**\n\n    ```bash\n    bun run preview\t\t\t\t# Preview staging build\n    bun run preview:prod\t\t\t# Preview production build\n    ```\n\n- **Testing**\n\n    ```bash\n    bun run test:lighthouse\t\t\t# Run Lighthouse performance tests\n    bun run test:axe\t\t\t# Run accessibility tests\n    ```\n\n- **Code Quality**\n\n    ```bash\n    bun run check\t\t\t\t# Run formatting, Svelte, and script checks\n    bun run check:ci\t\t\t# Run checks for CI pipeline\n    bun run check:all\t\t\t# Run all checks including build\n    bun run check:format\t\t\t# Check code formatting\n    bun run check:lint\t\t\t# Check code linting\n    bun run watch\t\t\t\t# Check code on file changes\n    bun run write\t\t\t\t# Fix formatting issues\n    ```\n\n- **Asset Management**\n\n    ```bash\n    bun run assets \t\t\t\t# Fetch and process images\n    bun run assets:fetch\t\t\t# Fetch assets from CMS\n    bun run assets:process\t\t\t# Process fetched assets\n    bun run assets:favicons\t\t\t# Generate favicons\n    ```\n\n---\n\n## Workflow\n\n### Content Workflow\n\nMikrouli integrates with Contentful for content management. The workflow:\n\n1. **Fetch Content:** Use `fetchContent.js` to retrieve raw data from\n   Contentful.\n2. **Transform Data:** Process the fetched data into structured JSON for\n   rendering.\n3. **Render Pages:** Build dynamic pages using the transformed data.\n\n### CI/CD Workflow\n\nGitHub Actions handles CI/CD using our [CI workflow](.github/workflows/ci.yml).\nThe workflow is documented in the [workflow documentation](docs/workflow.md).\n\n\u003e Environment secrets are\n\u003e [securely managed via GitHub](https://github.com/pvds/mikrouli/settings/secrets/actions).\n\n---\n\n## Development Principles\n\n### Core Principles\n\n- **Low Effort, High Impact:** Focus on delivering high-value features with\n  minimal complexity.\n- **Iterative Refinement:** Enhance features post-deployment to improve\n  usability, scalability, and maintainability.\n\n### Key Focus Areas\n\n1. **Ease of Use:** Prioritize intuitive setup and minimal configuration.\n2. **Performance:** Optimize for perceived performance as the top metric.\n3. **Accessibility:** Design with WCAG AA compliance in mind.\n4. **Simplicity:** Keep the platform straightforward for end users; embrace\n   complexity only if it improves maintainability or scalability.\n5. **Scalability:** Ensure systems support future growth and localization.\n6. **Web Standards First:** Use modern HTML/CSS features and minimize JavaScript\n   usage.\n7. **HTML/CSS-First:** Minimize JavaScript reliance, using polyfills sparingly.\n\n---\n\n## Project Structure\n\nThe project is modular and organized as follows, also refer to\n[sveltekit project structure](https://svelte.dev/docs/kit/project-structure):\n\n```\n.\n├── .github/                  # Github related files\n│   ├── actions/              # Composite actions used in workflows\n│   └── workflows/            # CI/CD workflows\n├── docs/                     # Project documentation\n├── images/                   # Soource images for the project\n├── scripts/                  # Node scripts\n│   ├── assets/               # Asset related scripts\n│   │   ├── fetch.js          # Fetch CMS images\n│   │   └── process.js        # Process local and CMS images\n│   ├── content/              # CMS content scripts\n│   │   ├── fetch.js          # Fetch CMS content\n│   │   └── process.js        # Process content data\n│   ├── test/                 # Testing scripts\n│   └── util/                 # Utility scripts\n├── src/                      # Svelte source code\n│   ├── data/                 # JSON data files\n│   │   ├── generated/        # Generated JSON data files\n│   │   ├── global.json       # Global application data\n│   │   └── seo.json          # Default SEO data\n│   ├── lib/                  # Svelte library files\n│   │   ├── components/       # Svelte components\n│   │   │   ├── global/       # Application shell components\n│   │   │   ├── layout/       # Structural layout components\n│   │   │   ├── ui/           # Reusable UI components\n│   │   │   ├── visuals/      # Decorative visual components\n│   │   ├── helpers/          # Helper functions\n│   │   ├── server/           # Server-only code\n│   │   ├── styles/           # Global styling\n│   │   └── types/            # Typing d.ts files for usage in jsdoc\n│   ├── routes/               # SvelteKit route handlers\n│   └── config.js             # Project configuration constants\n├── static/                   # Static assets (copied to build)\n│   ├── fonts/                # Font files\n│   ├── images/               # Image assets\n│   │   ├── cms/              # Optimized CMS images (generated)\n│   │   └── local/            # Optimized local images from (generated)\n│   └── pwa/                  # PWA assets (manifest, icons, images)\n├── .editorconfig             # Editor configuration\n├── .env                      # Environment variables (see .env.example)\n├── .gitignore                # Git ignore rules\n├── .npmrc                    # npm configuration\n├── biome.jsonc               # Linting and formatting configuration\n├── bun.lockb                 # Bun lock file\n├── favicons.json             # Favicon configuration\n├── jsconfig.json             # JavaScript configuration\n├── lefthook.yml              # Git hooks configuration\n├── package.json              # Project metadata\n├── svelte.config.js          # Svelte configuration\n└── vite.config.js            # Vite configuration\n```\n\n---\n\n## Troubleshooting\n\n| **Issue**               | **Solution**                                                              |\n| ----------------------- | ------------------------------------------------------------------------- |\n| Installation fails      | Verify Node.js and Bun versions meet requirements.                        |\n| Contentful fetch errors | Ensure `.env` exists and contains valid Contentful keys, see .env.example |\n| Build or dev errors     | Run the clean script: `bun run util:clean`.                               |\n\n---\n\n## Guidelines\n\n### Tailwind\n\n#### Using @apply\n\nIn general, `@apply` is not recommended. In some cases it can be useful:\n\n- you don't have control over the HTML structure (e.g. when using a 3rd party\n  component)\n- styling elements that cannot be targeted with a class (e.g. scrollbar)\n\nAlternative to using `@apply`:\n\n- use the theme() and screen() functions to access Tailwind's configuration\n\nThis serves as an example on how to do it (using @reference)\n\n- theme.css allows accessing generated theme classes\n- utilities.css allows accessing generated custom utility classes\n\n```html\n\u003cstyle\u003e\n\t@reference \"$lib/styles/theme.css\";\n\t@reference \"$lib/styles/utilities.css\";\n\n\t.nav-menu--bottom {\n\t\t@apply w-full flex justify-around fixed left-0 bottom-0 bg-primary-900 px-1 py-2;\n\t}\n\n\t.nav-menu--inline {\n\t\t@apply flex relative gap-2 bg-primary-900;\n\t}\n\n\t.nav-menu__link {\n\t\t@apply inline-block w-full text-center px-3 py-1 font-semibold;\n\t}\n\u003c/style\u003e\n```\n\n## Documentation\n\nExplore more in the `docs/` directory:\n\n- **[Brand Guide](docs/brand-guide.md):** Branding and style guidelines.\n- **[JSDoc Guide](docs/jsdoc.md):** Using JSDoc for type safety in JavaScript\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvds%2Fmikrouli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpvds%2Fmikrouli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvds%2Fmikrouli/lists"}