---

🚀 Introduction

TEDI Stack is an open-source, learn-in-public project that combines modern web technologies to create a powerful full-stack development environment. Built on the foundation of React Router v7 framework with Bun runtime and Hono server, this stack is designed to enable fast, efficient, and type-safe web application development.

⚠️ Experimental Notice: This project should be considered experimental as the combination of React Router v7 framework with Bun runtime and Hono server is not yet fully supported in all areas. Feel free to contribute, suggest improvements, or provide feedback!

🌟 Inspiration

This stack draws inspiration from several excellent projects:

• Epic Stack by Kent C. Dodds - The primary inspiration for TEDI Stack. Initially, I tried to create an example of the Epic Stack with Hono and Bun runtime but ran into several challenges, which led to the creation of TEDI Stack.

• Base Stack by Alem Tulzak - A great source of inspiration, particularly for the Hono server configuration and i18next integration.

🛠️ Key Technologies

Technology	Description	Link
	Full-featured framework for building web applications	reactrouter.com
	JavaScript runtime, bundler, test runner, and package manager	bun.sh
	Fast, lightweight web framework	hono.dev
	Utility-first CSS framework	tailwindcss.com
	Typed JavaScript	typescriptlang.org
	TypeScript-first schema validation	zod.dev
	Formatter, linter, and more	biomejs.dev
	Internationalization framework	i18next.com
	App deployment platform	fly.io
	Secure environment variable management	1password.com
	Containerization platform	docker.com
	Version control platform	github.com
	Error tracking	sentry.io
	Product analytics platform	posthog.com

📋 Features

• React Router v7 - Full-featured framework capabilities with SSR
• Bun Runtime - Fast JavaScript runtime with built-in bundler
• Hono Server - Lightweight and efficient server for handling requests
• TypeScript - Type-safe code development
• Tailwind CSS - Utility-first styling approach
• i18next - Internationalization support
• 1Password Integration - Secure environment variable management
• Biome - Modern formatter and linter
• GitHub Actions - CI/CD workflows for automated deployments
• Fly.io Deployment - Easy cloud deployment

📊 Analytics & Error Tracking

Sentry Integration

TEDI Stack comes with Sentry integration for error tracking and performance monitoring. To enable Sentry:

1. Create a Sentry account and project at sentry.io
2. Add the following environment variables to your .env file:

# SENTRY
SENTRY_DSN="your-sentry-dsn"
SENTRY_AUTH_TOKEN="your-sentry-auth-token"
SENTRY_ORG="your-sentry-organization"
SENTRY_PROJECT="your-sentry-project-name"

Sentry will automatically capture errors and exceptions in both server and client environments when these environment variables are present.

PostHog Integration

TEDI Stack includes PostHog for product analytics and user behavior tracking. To enable PostHog:

1. Create a PostHog account and project at posthog.com
2. Add the following environment variables to your .env file:

# POSTHOG
POSTHOG_API_KEY="your-posthog-api-key"
POSTHOG_API_ENDPOINT="your-posthog-api-endpoint" # Usually https://app.posthog.com or your self-hosted URL

The integration includes automatic page view tracking and supports identifying users for cohort analysis.

🚦 Getting Started

Prerequisites

• Bun installed
• Optional: 1Password CLI for secure environment variable management
• Optional: Docker for containerization

1Password CLI Setup

TEDI Stack uses 1Password CLI to securely manage environment variables. To set up:

1. Install the 1Password CLI following the official installation guide

2. Sign in to your 1Password account:

   op account add
   

3. Create an .env.op file at the root of your project with references to your secrets:

   SENTRY_DSN=op://YourVault/SENTRY/SENTRY_DSN
   SENTRY_AUTH_TOKEN=op://YourVault/SENTRY/SENTRY_AUTH_TOKEN
   # other environment variables...
   

4. Use the development script that loads variables from 1Password:

   bun dev:op
   

Installation

# Clone the repository
git clone https://github.com/koikar/tedi-stack.git
cd tedi-stack

# Install dependencies
bun install

# Start the development server
bun dev

Deployment

To deploy to Fly.io:

1. Install the Flyctl CLI: Installation Guide
2. Log in to Fly: fly auth login
3. Deploy the app: fly deploy

For CI/CD deployment using GitHub Actions, see the workflows defined in .github/workflows/.

📁 Project Structure

TEDI Stack follows a logical directory structure to organize code efficiently:

tedi-stack/
├── app/                   # Main application code
│   ├── components/        # Reusable React components
│   ├── routes/            # General routes, layouts and resource routes
│   ├── utils/             # Utility functions and helpers
│   ├── localization/      # Internationalization files
│   └── features/          # Feature modules
│       ├── marketing/     # Marketing feature
│       ├── analytics/     # Analytics feature
│       ├── authentication/# Authentication feature
│       └── user/          # User management feature
│           ├── components/# Feature-specific components
│           ├── routes/    # Feature-specific routes
│           ├── utils/     # Feature-specific utilities
│           ├── constants/ # Feature-specific constants
│           ├── types/     # Feature-specific types
│           └── server/    # Feature-specific server code
├── public/                # Static files served directly
│   └── favicons/          # Various favicon formats for different devices
├── other/                 # Miscellaneous files and configurations
├── server/                # Hono server configuration
└── tests/                 # Test files for the application

Each feature module in app/features/ follows a similar structure, promoting code organization and modularity.

🤝 Contributing

Contributions to TEDI Stack are welcome! Here's how you can contribute:

1. Fork the Repository: Create your own fork of the project
2. Submit a Pull Request: Once you've tested your changes, submit a PR to the main repository

❓ Troubleshooting

Common Issues

1. Environment Variable Problems: Ensure all required environment variables are properly set or configured in 1Password.

2. Build Failures: Make sure you're using the correct version of Bun. Check with bun --version and update if needed.

3. 1Password Integration Issues: Verify that the 1Password CLI is correctly installed and authenticated. Run op account list to confirm.

4. Deployment Errors: When deploying to Fly.io, check that your fly.toml configuration is correct and you have the necessary permissions.

For more help, please open an issue on GitHub.