Mikrouli Development Platform

Platform for systemic change.

Mikrouli leverages a modern web platform, combining performance, scalability, and maintainability. It is built using SvelteKit, Tailwind CSS, and powered by Contentful as a headless CMS. The platform emphasizes a seamless developer experience and user-centric design.

---

Table of Contents

• Features
• Getting Started
• Scripts
• Workflow
• Development Principles
• Project Structure
• Troubleshooting
• Documentation

---

Features

Development Tools

• SvelteKit: Framework for building modern web applications.
• Tailwind CSS: Utility-first CSS framework.
• Bun: High-performance JavaScript runtime and package manager.
• Vite: High-speed build tool.

Testing and Quality Assurance

• Vitest: Unit testing framework.
• Playwright: End-to-end testing tool.
• Biome: Linting and formatting.
• Lefthook: Git hooks for automated checks.

Hosting and CMS

• GitHub Pages: Static hosting.
• Contentful: Headless CMS for managing content.

---

Getting Started

Install Dependencies

For macOS we recommend using Homebrew For Windows we recommend using Scoop

1. Install Node.js (v22 or newer):
   Follow the Node.js documentation.

   • macOS: brew install node or brew install nvm
   • windows: scoop install nodejs or use nvm for windows

2. Install Bun (v1 or newer):
   Follow the Bun installation guide.

   • macOS/Linux: brew install oven-sh/bun/bun or curl -fsSL https://bun.sh/install | bash
   • windows: scoop bucket add main && scoop install bun or powershell -c "irm bun.sh/install.ps1 | iex"

3. Install project dependencies:

   bun install

Local Development

Quick start by running bun i && bun start.

bun start is a shorthand for bun dev --open & bun run watch.

1. Install dependencies:

   bun install

2. Start the development server:

   bun run dev --open

3. Optionally, run the svelte-check watcher for code checks:

   bun run watch

Environment Variables

To fetch live content from Contentful, add a .env file to the project root, you can use .env.example file as a template:

CONTENTFUL_SPACE_ID=<Your Contentful Space ID>
CONTENTFUL_ACCESS_TOKEN=<Your Contentful Access Token>
PUBLIC_ENVIRONMENT=development

---

Scripts

• Development Server:

  bun run dev

• Build:

  bun run build

• Code Checks:

  bun run check

• Fetch Content:

  bun run util:content

• Clean and Reset:

  bun run util:clean

---

Workflow

Content Workflow

Mikrouli integrates with Contentful for content management. The workflow:

1. Fetch Content: Use fetchContent.js to retrieve raw data from Contentful.
2. Transform Data: Process the fetched data into structured JSON for rendering.
3. Render Pages: Build dynamic pages using the transformed data.

CI/CD Workflow

GitHub Actions handles CI/CD:

1. Build Stage: Lint, check, and build the project on every push to main.
2. Deploy Stage: Deploy artifacts to GitHub Pages.

Secrets such as CONTENTFUL_SPACE_ID and CONTENTFUL_ACCESS_TOKEN are securely managed via GitHub.

---

Development Principles

Core Principles

• Low Effort, High Impact: Focus on delivering high-value features with minimal complexity.
• Iterative Refinement: Enhance features post-deployment to improve usability, scalability, and maintainability.

Key Focus Areas

1. Ease of Use: Prioritize intuitive setup and minimal configuration.
2. Performance: Optimize for perceived performance as the top metric.
3. Accessibility: Design with WCAG AA compliance in mind.
4. Simplicity: Keep the platform straightforward for end users; embrace complexity only if it improves maintainability or scalability.
5. Scalability: Ensure systems support future growth and localization.
6. Web Standards First: Use modern HTML/CSS features and minimize JavaScript usage.
7. HTML/CSS-First: Minimize JavaScript reliance, using polyfills sparingly.

---

Project Structure

The project is modular and organized as follows, also refer to sveltekit project structure:

.
├── docs/                 # Project documentation
├── scripts/              # Helper scripts
├── src/                  # Application source code
│   ├── lib/
│   │   ├── components/   # Svelte UI components
│   │   ├── images/       # Image assets
│   │   ├── data/         # JSON data files (generated from contentful)
│   │   ├── server/       # Server-only lib files
│   │   ├── styles/       # Global styling
│   │   └── types /       # Typing d.ts files for usage in jsdoc
│   ├── routes/           # SvelteKit route handlers
│   └── static/           # Static assets (e.g., favicon.svg)
├── .editorconfig         # Editor configuration
├── .env                  # Environment variables (see .env.example)
├── .gitignore            # Git ignore rules
├── .npmrc                # npm configuration
├── biome.jsonc           # Linting and formatting configuration
├── bun.lockb             # Bun lock file
├── favicons.json         # Favicon configuration
├── jsconfig.json         # JavaScript configuration
├── lefthook.yml          # Git hooks configuration
├── package.json          # Project metadata
├── svelte.config.js      # Svelte configuration
└── vite.config.js        # Vite configuration

---

Troubleshooting

Issue	Solution
Installation fails	Verify Node.js and Bun versions meet requirements.
Environment variable errors	Ensure .env exists and contains valid Contentful keys, see .env.example
Contentful fetch errors	Check API keys and network connectivity.
Build or dev errors	Run the clean script: bun run util:clean.

---

Documentation

Explore more in the docs/ directory:

• Brand Guide: Branding and style guidelines.
• JSDoc Guide: Using JSDoc for type safety in JavaScript