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 content:cms
  

• 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

Guidelines

Tailwind

Using @apply

In general, @apply is not recommended. In some cases it can be useful:

• you don't have control over the HTML structure (e.g. when using a 3rd party component)
• styling elements that cannot be targeted with a class (e.g. scrollbar)

Alternative to using @apply:

• use the theme() and screen() functions to access Tailwind's configuration

This serves as an example on how to do it (using @reference)

• theme.css allows accessing generated theme classes
• utilities.css allows accessing generated custom utility classes

<style>
    @reference "$lib/styles/theme.css";
    @reference "$lib/styles/utilities.css";

    .nav-menu--bottom {
        @apply w-full flex justify-around fixed left-0 bottom-0 bg-primary-900 px-1 py-2;
    }

    .nav-menu--inline {
        @apply flex relative gap-2 bg-primary-900;
    }

    .nav-menu__link {
        @apply inline-block w-full text-center px-3 py-1 font-semibold;
    }
</style>

Documentation

Explore more in the docs/ directory:

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