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.
• Bun: High-performance JavaScript runtime and package manager.
• Vite: High-speed build tool.

Styling

• Tailwind CSS: Utility-first CSS framework.

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: Staging environment host
• Netlify: Production environment host
• Contentful: Headless CMS for managing content.

Analytics and Monitoring

• Umami: Privacy-focused analytics.

Email

• forwardemail: Privacy focussed email service provider

---

Getting Started

If you already have all dependencies quick start by running bun i && bun start.

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

Prerequisites

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

4. Set up the project:

   bun run util:prepare

Local Development

1. Install dependencies:

   bun install

2. Start the development server:

   bun start

---

Scripts

• Setup

  bun run prepare        		# Install git hooks with Lefthook

• Development

  bun run start          		# Start development server and watch for changes
  bun run start:prod     		# Build and start production server

• Build

  bun run build              	# Build for staging
  bun run build:prod   	# Build for production

• Preview

  bun run preview            	# Preview staging build
  bun run preview:prod 	# Preview production build

• Testing

  bun run test:lighthouse 	# Run Lighthouse performance tests
  bun run test:axe        	# Run accessibility tests

• Watching

  bun run watch       		# Watch for changes in code

• Code Quality

  bun run check         		# Run formatting, Svelte, and script checks
  bun run check:ci      		# Run checks for CI pipeline
  bun run check:all      		# Run all checks including build
  bun run check:format    	# Check code formatting
  bun run check:lint	    	# Check code linting
  bun run write          		# Fix formatting issues

• Content Management

  bun run content         	# Fetch content and process assets
  bun run content:fetch   	# Fetch content from CMS

• Asset Management

  bun run assets          	# Fetch and process images
  bun run assets:fetch    	# Fetch assets from CMS
  bun run assets:process  	# Process fetched assets
  bun run assets:favicons 	# Generate favicons

• Workspace Management

  bun run workspace:prepare 	# Prepare the workspace
  bun run workspace:clean   	# Clean the workspace

---

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 using our CI workflow. The workflow is documented in the workflow documentation.

Environment secrets 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:

.
├── .github/                  # Github related files
│   ├── actions/              # Composite actions used in workflows
│   └── workflows/            # CI/CD workflows
├── docs/                     # Project documentation
├── images/                   # Soource images for the project
├── scripts/                  # Node scripts
│   ├── assets/               # Asset related scripts
│   │   ├── fetch.js          # Fetch CMS images
│   │   └── process.js        # Process local and CMS images
│   ├── content/              # CMS content scripts
│   │   ├── fetch.js          # Fetch CMS content
│   │   └── process.js        # Process content data
│   ├── test/                 # Testing scripts
│   └── util/                 # Utility scripts
├── src/                      # Svelte source code
│   ├── data/                 # JSON data files
│   │   ├── generated/        # Generated JSON data files
│   │   ├── global.json       # Global application data
│   │   └── seo.json          # Default SEO data
│   ├── lib/                  # Svelte library files
│   │   ├── components/       # Svelte components
│   │   │   ├── global/       # Application shell components
│   │   │   ├── layout/       # Structural layout components
│   │   │   ├── ui/           # Reusable UI components
│   │   │   ├── visuals/      # Decorative visual components
│   │   ├── helpers/          # Helper functions
│   │   ├── server/           # Server-only code
│   │   ├── styles/           # Global styling
│   │   └── types/            # Typing d.ts files for usage in jsdoc
│   ├── routes/               # SvelteKit route handlers
│   └── config.js             # Project configuration constants
├── static/                   # Static assets (copied to build)
│   ├── fonts/                # Font files
│   ├── images/               # Image assets
│   │   ├── cms/              # Optimized CMS images (generated)
│   │   └── local/            # Optimized local images from (generated)
│   └── pwa/                  # PWA assets (manifest, icons, images)
├── .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.
Contentful fetch errors	Ensure .env exists and contains valid Contentful keys, see .env.example
Build or dev errors	Run the clean script: bun run util:clean.

---

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