Forem: Evgenii Fedotov

Single-Node Kubernetes for Devs and Small Projects: Hetzner + Cluster API = ❤️

Evgenii Fedotov — Fri, 27 Jun 2025 09:27:40 +0000

If you need a simple, small, and cost-efficient Kubernetes all-in-one-node solution for development, testing, or small cloud-native projects, my open-source tool cluster-api-hetzner-k8s-one-node is here to help. It automates setting up a fully functional Kubernetes cluster on a single Hetzner Cloud node using Makefiles and kubeadm, built on top of the Cluster API Provider for Hetzner (CAPH). This setup is ideal for lightweight, reproducible environments. It includes everything you need: control plane, workloads, MetalLB for local load balancing, Flannel for networking, Hetzner CSI for storage, and Traefik as the ingress controller — all running efficiently on one node.

🧱 Infrastructure Overview

Everything runs on a single node, including the control plane, workloads, and all supporting components. No external load balancer is needed, which saves both cost and complexity. The stack includes:

MetalLB — local load balancing (enables LoadBalancer services without cloud provider integration)
Flannel — simple, reliable CNI networking
Hetzner CSI — seamless storage integration with Hetzner Cloud
Traefik — an ingress controller for easy access to your services

This delivers a fully functional, production-like Kubernetes environment in a compact, efficient package — perfect for experimentation, demos, or small internal projects. Especially useful for solo developers or small teams looking to save time and money.

⚙️ About CAPH and Syself

This tool is powered by the Cluster API Provider for Hetzner (CAPH), developed and maintained by Syself. Syself is dedicated to making Kubernetes management easy and accessible. CAPH brings declarative, Kubernetes-native cluster management to Hetzner, enabling powerful automation and infrastructure-as-code workflows.

🚀 Key Features

Single-node simplicity — perfect for dev, test, or small projects
No external load balancer — MetalLB reduces costs and complexity
Automated setup — streamlined with Makefiles, no manual configs
Hetzner Cloud integration — cost-effective, powerful infrastructure
Kubernetes-native — built with Cluster API and kubeadm for compatibility
Complete stack — networking, storage, and ingress included

☁️ Need Production-Ready Kubernetes?

For a more robust, fully-managed Kubernetes experience on Hetzner, Syself offers a production-grade managed service that handles lifecycle, scaling, security, and more — so you can focus on shipping code instead of infrastructure. When your project grows, upgrading is seamless.

🔗 Useful Links

Learn more about CAPH: https://caph.syself.com
Try the tool on GitHub: https://github.com/lieranderl/cluster-api-hetzner-k8s-one-node/
Explore Syself Managed Kubernetes: https://syself.com/hetzner

🚀 Building a Smart Cisco Webex Bot: Harnessing LangGraph's Stateful LLM Agents for AI-Powered Assistance 🤖✨

Evgenii Fedotov — Sat, 12 Oct 2024 22:07:03 +0000

Introduction: The Power of AI-Assisted Communication in Webex

In today's fast-paced digital workplace, effective communication is key. Imagine having an intelligent assistant in your Cisco Webex Teams that can search the web, retrieve user information, and perform calculations - all while maintaining context across conversations. That's exactly what we're going to build in this tutorial!

By the end of this guide, you'll have created a powerful AI-powered Webex bot using LangGraph's stateful large language model (LLM) agents. This bot will enhance your team's interactions within Webex by providing intelligent responses and performing complex tasks efficiently.

Project Overview: What We're Building and Why

Our Webex Bot AI Assistant will leverage the following key technologies:

🧠 LangChain & LangGraph: For building stateful, multi-actor AI applications
🚀 OpenAI: Providing the underlying language model
🤖 Webex Bot lib: For seamless integration with Webex Teams leveraging WebSockets
📊 SQLite: Lightweight database for maintaining conversation history

Key Features:

🔍 Web search capabilities with Tavily Search
👤 Retrieval of Webex user information
🧮 Mathematical operations (e.g., calculating a number's power)
💾 Persistent conversation history for improved context awareness

Prerequisites:

Basic knowledge of Python
Understanding of bot frameworks (helpful, but not required)
Understanding of LangGraph agents (helpful, but not required)

Let's dive in and start building!

Setting Up Your Development Environment

Before we start coding, let's set up our environment:

1. Clone the project repository:

   git clone https://github.com/lieranderl/webexbot-langgraph-assistant-template

2. Create a .env file in the project root with the following variables:

   # LLM ENVIRONMENT
   OPENAI_API_BASE=<OpenAI API base URL>
   OPENAI_API_KEY=<Your OpenAI API key>
   LLM_MODEL=<Name of llm model>

   # LANGCHAIN ENVIRONMENT
   LANGCHAIN_ENDPOINT=<LangSmith endpoint URL>
   LANGCHAIN_API_KEY=<Your LangSmith API key>
   LANGCHAIN_PROJECT=<Name of your LangSmith project>

   # Tools API
   TAVILY_API_KEY=<Your Tavily API key for web search>

   # SQLite Database for Conversation History
   SQL_CONNECTION_STR=checkpoints.db

   # Webex Bot Configuration
   WEBEX_TEAMS_ACCESS_TOKEN=<Your Webex Bot Access Token>
   WEBEX_TEAMS_DOMAIN=<Your Webex Domain>

3. Install dependencies using Poetry:

   poetry install

Now that our environment is set up, let's start building our AI assistant!

Project Structure and SOLID Principles

Our project follows a structure that promotes better organization, maintainability, and adheres to SOLID principles:

project_root/
│
├── src/
│   ├── graph_reactagent/
│   │   ├── __init__.py
│   │   ├── interfaces.py
│   │   ├── graph.py
│   │   ├── invoker.py
│   │   ├── messages_filter.py
│   │   ├── prompt_formatter.py
│   │   └── tools.py
│   │
│   └── webexbot/
│       ├── __init__.py
│       ├── commands.py
│       └── webexbot.py
│
├── tests/
│   ├── __init__.py
│   ├── test_graph_reactagent.py
│   ├── test_messages_filter.py
│   ├── test_tools.py
│   └── test_webexbot.py
│
├── .env
├── .coveragerc
├── pyproject.toml
└── README.md

This structure separates concerns and allows for easier extension and modification of individual components. Let's dive into some key files and how they embody SOLID principles:

interfaces.py

The interfaces.py file defines the interfaces (protocols in Python) that our classes will implement. This adheres to the Interface Segregation Principle (the 'I' in SOLID) by providing specific interfaces for different functionalities.

from typing import Protocol, Any, Dict, List
from datetime import datetime
from langchain_core.messages import AnyMessage

class IMessageFilter(Protocol):
    def filter_messages(self, messages: List[AnyMessage]) -> List[AnyMessage]: ...

class IPromptFormatter(Protocol):
    def format_prompt(
        self, messages: List[AnyMessage], system_time: datetime
    ) -> Any: ...

class IGraphInvoker(Protocol):
    def invoke(self, message: str, **kwargs: Any) -> Dict[str, Any]: ...

These interfaces allow us to define the contract that classes must follow without specifying the implementation. This promotes loose coupling and makes our system more modular and easier to extend.

messages_filter.py

The messages_filter.py file contains the implementation of our message filtering logic. This adheres to the Single Responsibility Principle (the 'S' in SOLID) by focusing solely on the task of filtering messages.

from typing import List
from langchain_core.messages import HumanMessage, AIMessage, ToolMessage, AnyMessage
from graph_reactagent.interfaces import IMessageFilter


class DefaultMessageFilter(IMessageFilter):
    def filter_messages(self, messages: List[AnyMessage]) -> List[AnyMessage]:
        message_count = min(6, len(messages))
        filtered_messages = messages[-message_count:]

        while message_count > 1:
            if isinstance(filtered_messages[0], HumanMessage):
                break
            message_count -= 1
            while message_count > 0 and isinstance(
                messages[-message_count], (AIMessage, ToolMessage)
            ):
                # we cannot have an assistant message at the start of the chat history
                # if after removal of the first, we have an assistant message,
                # we need to remove the assistant message too
                # all tool messages should be preceded by an assistant message
                # if we remove a tool message, we need to remove the assistant message too
                message_count -= 1
            filtered_messages = messages[-message_count:]
        return filtered_messages

This implementation ensures that we maintain a manageable context window for our AI model by limiting the number of messages passed to it. It also makes sure that tool-related messages are properly contextualized by including the message that triggered the tool use.

prompt_formatter.py

The prompt_formatter.py file handles the formatting of our prompts. This adheres to the Open/Closed Principle (the 'O' in SOLID) by allowing for easy extension of formatting behavior without modifying existing code.

from typing import Any, List
from datetime import datetime
from langchain_core.prompts import ChatPromptTemplate
from .interfaces import IPromptFormatter
from langchain_core.messages import AnyMessage

class DefaultPromptFormatter(IPromptFormatter):
    def __init__(self, prompt: ChatPromptTemplate):
        self.prompt = prompt

    def format_prompt(self, messages: List[AnyMessage], system_time: datetime) -> Any:
        return self.prompt.invoke(
            {
                "messages": messages,
                "system_time": system_time.isoformat(),
            }
        )

This formatter takes a ChatPromptTemplate and uses it to format the messages and system time into a prompt suitable for our AI model. By using a template, we can easily modify the prompt structure without changing the formatting logic.

Crafting the Brain: Building the ReAct Agent with LangGraph

Now that we've covered our supporting files, let's take a deeper look at how we build our ReAct agent in the graph.py file:

from typing import Any, Dict
from datetime import datetime, timezone
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent, ToolNode
from langchain_core.prompts import ChatPromptTemplate
from .interfaces import IMessageFilter, IPromptFormatter
from .messages_filter import DefaultMessageFilter
from .prompt_formatter import DefaultPromptFormatter
from .tools import search, get_webex_user_info, power

SYSTEM_PROMPT = """You are a helpful AI assistant in a Webex chat. 
Your primary tasks include:
1. Searching the web to provide relevant information.
2. Retrieving personal information from Webex.
3. Performing power calculations.
4. Interacting with users to assist with their queries.
Ensure your responses are clear, accurate, and concise. Always aim to provide the most helpful information based on the user's request.
System time: {system_time}"""

class Graph:
    def __init__(
        self,
        model: str,
        tools: list,
        message_filter: IMessageFilter,
        prompt_formatter: IPromptFormatter,
        name: str = "ReAct Agent",
    ):
        self.model = ChatOpenAI(model=model)
        self.tools = ToolNode(tools)
        self.message_filter = message_filter
        self.prompt_formatter = prompt_formatter
        self.name = name

        self.graph = self._create_graph()

    def _create_graph(self):
        graph = create_react_agent(
            self.model, self.tools, state_modifier=self._format_for_model
        )
        graph.name = self.name
        return graph

    def _format_for_model(self, state: Dict[str, Any]) -> Any:
        messages = state["messages"]
        filtered_messages = self.message_filter.filter_messages(messages)
        return self.prompt_formatter.format_prompt(
            filtered_messages, datetime.now(timezone.utc).astimezone()
        )

def create_default_graph():
    prompt = ChatPromptTemplate.from_messages(
        [
            ("system", SYSTEM_PROMPT),
            ("placeholder", "{messages}"),
        ]
    )
    tools = [get_webex_user_info, search, power]
    return Graph(
        model="gpt-4o",
        tools=tools,
        message_filter=DefaultMessageFilter(),
        prompt_formatter=DefaultPromptFormatter(prompt),
        name="Webex Bot Demo ReAct Agent",
    )

This Graph class encapsulates the creation and configuration of our ReAct agent. It uses dependency injection (adhering to the Dependency Inversion Principle, the 'D' in SOLID) to allow for flexible message filtering and prompt formatting.

The _format_for_model method ties together our message filtering and prompt formatting. It first applies the message filter to limit the context window, then uses the prompt formatter to prepare the input for our AI model.

By structuring our code this way, we've created a flexible and extensible system that can easily accommodate changes or additions to our bot's capabilities. For example, if we wanted to implement a different message filtering strategy or change our prompt format, we could do so by creating new classes that implement the IMessageFilter or IPromptFormatter interfaces, respectively, without having to modify the existing Graph class.

This setup creates a powerful ReAct agent that can understand context, use tools, and generate appropriate responses.

Empowering Your Bot: Implementing Custom Tools

Our bot's capabilities are enhanced by custom tools. Let's look at the key tools in our tools.py file:

1. Web Search Tool:

def search(
    query: str, *, config: Annotated[RunnableConfig, InjectedToolArg]
) -> Optional[List[Dict[str, Any]]]:
    """Search for general web results.
       Search for real-time information using the Tavily search engine.

    This function performs a search using the Tavily search engine, which is designed
    to provide comprehensive, accurate, and trusted results. It's particularly useful
    for answering questions about current events.
    """
    max_results: int = config.get("configurable", {}).get("max_results") or 5
    wrapped = TavilySearchResults(max_results=max_results)
    result = wrapped.invoke({"query": query})
    return cast(List[Dict[str, Any]], result)

2. Power Calculation Tool:

def power(a: int, b: int) -> int:
    """Calculate power of a number."""
    return a**b

3. Webex User Info Retrieval Tool:

def get_webex_user_info(
    config: Annotated[RunnableConfig, InjectedToolArg],
) -> Optional[Dict[str, str]]:
    """Get user information: email and user name/display name from Webex SDK"""
    displayName: str = config.get("configurable", {}).get("displayName") or ""
    email: str = config.get("configurable", {}).get("email") or ""

    return {
        "displayName": displayName,
        "email": email,
    }

These tools allow our bot to perform web searches, mathematical calculations, and retrieve user information from Webex.

Maintaining Context: Checkpointing with SQLite

To ensure our bot maintains context across conversations, we use SQLite for checkpointing. Here's how we set it up in our invoker.py file:

class GraphInvoker(IGraphInvoker):
    def __init__(
        self,
        graph: Graph,
        connection_str: str = "",
        llm_model: str = "",
        temperature: float = 0.1,
    ):
        self.graph = graph
        self.connection_str = connection_str or os.getenv("SQL_CONNECTION_STR")
        self.llm_model = llm_model or os.getenv("LLM_MODEL")
        self.temperature = temperature

    def invoke(self, message: str, **kwargs: Any) -> Dict[str, Any]:
        if not self.connection_str:
            raise ValueError("No database connection string provided")
        if not self.llm_model:
            raise ValueError("No LLM model provided")
        with SqliteSaver.from_conn_string(self.connection_str) as saver:
            self.graph.graph.checkpointer = saver
            run_id = uuid4()
            config = RunnableConfig(
                configurable={
                    "model": self.llm_model,
                    "temperature": self.temperature,
                    **kwargs,
                },
                run_id=run_id,
            )
            result = self.graph.graph.invoke(
                input={"messages": [HumanMessage(content=message)]},
                config=config,
            )
            return result

This setup ensures that the conversation state persists between interactions.

Bringing It All Together: Integrating with Webex Teams

Now, let's integrate our AI assistant with Webex Teams.

First, we need to create and register the bot on Webex. For instructions on how to create and register your bot, please follow the Webex Bot guide

In our webexbot.py file:

def create_bot():
    load_dotenv()

    graph = create_default_graph()
    invoker = GraphInvoker(graph)
    openai_command = OpenAI(invoker)

    return WebexBot(
        teams_bot_token=os.getenv("WEBEX_TEAMS_ACCESS_TOKEN"),
        approved_domains=[os.getenv("WEBEX_TEAMS_DOMAIN")],
        bot_name="AI-Assistant",
        bot_help_subtitle="",
        threads=False,
        help_command=openai_command,
    )

if __name__ == "__main__":
    bot = create_bot()
    bot.run()

And in our commands.py file:

class OpenAI(Command):
    def __init__(self, invoker: IGraphInvoker):
        super().__init__()
        self.invoker = invoker

    def execute(self, message, attachment_actions, activity):
        response = self.invoker.invoke(
            message,
            thread_id=activity["target"]["globalId"],
            email=activity["actor"]["id"],
            displayName=activity["actor"]["displayName"],
            max_results=5,
        )
        return response["messages"][-1].content

This setup allows our bot to process all text inputs using our ReAct agent and respond within Webex Teams.

🚀 Running your AI Assistant

This project uses Poetry for dependency management and Poe the Poet for task running. Read more in readme

To start your Webex Bot AI Assistant, use the following command:

poe start

poetry run python -m webexbot.webexbot

Your bot is now live and ready to assist users in Webex Teams!

Example Interaction

Supercharging Development: Tracing and Analyzing with LangSmith

To gain insights into your bot's performance and behavior, we've integrated LangSmith for tracing. This allows you to visualize the decision-making process of your AI assistant and optimize its performance.

Conclusion: Your Webex Bot AI Assistant in Action

Congratulations! You've successfully built a powerful Webex Bot AI Assistant using LangGraph's stateful LLM agents. Your bot can now:

Understand and maintain context in conversations
Perform web searches for up-to-date information
Retrieve Webex user information
Calculate a number's power
Provide intelligent responses to user queries

This AI-powered assistant will significantly enhance communication and productivity within your Webex Teams environment.

Customizing Your Webex Bot AI Assistant

While the Webex Bot AI Assistant we've built provides a solid foundation, you may want to adapt it for your specific use cases. Here are some ways you can customize the bot to better suit your needs:

1. Adding New Tools

One of the most straightforward ways to extend your bot's capabilities is by adding new tools. Here's how you can do this:

1. Define a new tool function in `tools.py`:

def new_custom_tool(query: str, config: Annotated[RunnableConfig, InjectedToolArg]) -> str:
    # Implement your custom tool logic here
    return f"Result of custom tool for query: {query}"

2. Add the new tool to the `create_default_graph` function in `graph.py`:

def create_default_graph():
    # ... existing code ...
    tools = [get_webex_user_info, search, power, new_custom_tool]
    return Graph(
        model="gpt-4o",
        tools=tools,
        message_filter=DefaultMessageFilter(),
        prompt_formatter=DefaultPromptFormatter(prompt),
        name="Webex Bot Demo ReAct Agent",
    )

3. Update the system prompt in `graph.py` to inform the AI about the new tool:

SYSTEM_PROMPT = """You are a helpful AI assistant in a Webex chat. 
Your primary tasks include:
1. Searching the web to provide relevant information.
2. Retrieving personal information from Webex.
3. Performing power calculations.
4. [Description of your new custom tool]
5. Interacting with users to assist with their queries.
Ensure your responses are clear, accurate, and concise. Always aim to provide the most helpful information based on the user's request.
System time: {system_time}"""

2. Customizing Message Filtering

If you need a different message filtering strategy, you can create a new class that implements the IMessageFilter interface:

class CustomMessageFilter(IMessageFilter):
    def filter_messages(self, messages: List[AnyMessage]) -> List[AnyMessage]:
        # Implement your custom filtering logic here
        return messages  # This is just a placeholder

Then, update the create_default_graph function to use your new filter:

def create_default_graph():
    # ... existing code ...
    return Graph(
        model="gpt-4o",
        tools=tools,
        message_filter=CustomMessageFilter(),
        prompt_formatter=DefaultPromptFormatter(prompt),
        name="Webex Bot Demo ReAct Agent",
    )

3. Modifying the Prompt Format

To change how the AI interprets messages, you can modify the prompt format. Create a new class implementing the IPromptFormatter interface:

class CustomPromptFormatter(IPromptFormatter):
    def __init__(self, prompt: ChatPromptTemplate):
        self.prompt = prompt

    def format_prompt(self, messages: List[AnyMessage], system_time: datetime) -> Any:
        # Implement your custom prompt formatting logic here
        return self.prompt.invoke(
            {
                "messages": messages,
                "system_time": system_time.isoformat(),
                # Add any additional context you want to include
            }
        )

Update the create_default_graph function to use your new formatter:

def create_default_graph():
    # ... existing code ...
    custom_prompt = ChatPromptTemplate.from_messages(
        [
            ("system", YOUR_CUSTOM_SYSTEM_PROMPT),
            ("placeholder", "{messages}"),
        ]
    )
    return Graph(
        model="gpt-4o",
        tools=tools,
        message_filter=DefaultMessageFilter(),
        prompt_formatter=CustomPromptFormatter(custom_prompt),
        name="Webex Bot Demo ReAct Agent",
    )

4. Integrating with External Services

You can enhance your bot by integrating it with external services relevant to your organization. For example, you might add a tool to query a company database or interact with a project management system.

Here's a simple example of how you might create a tool to interact with a hypothetical API:

import requests

def query_company_database(query: str, config: Annotated[RunnableConfig, InjectedToolArg]) -> str:
    api_key = config.get("configurable", {}).get("company_db_api_key")
    if not api_key:
        return "Error: API key for company database not provided"

    response = requests.get(f"https://api.company-database.com/query?q={query}", headers={"Authorization": f"Bearer {api_key}"})
    if response.status_code == 200:
        return response.json()["result"]
    else:
        return f"Error querying company database: {response.status_code}"

Remember to add the new API key to your .env file and update your bot's configuration to pass it to the tool.

By leveraging these customization techniques, you can adapt the Webex Bot AI Assistant to better fit your organization's specific needs and workflows. Whether you're adding new capabilities, changing how the bot processes messages, or integrating with your existing systems, the modular design of the bot makes these customizations straightforward to implement.

Troubleshooting

If you encounter any issues while setting up or running your bot, check these common problems:

API Key Issues: Ensure all API keys in your .env file are correct and up-to-date.
Dependency Conflicts: Make sure you're using the correct versions of all libraries. Check the pyproject.toml file for version specifications.
Webex Integration: If your bot isn't responding in Webex, verify that your bot's access token is correct and that it has the necessary permissions.

For more specific issues, consult the documentation of the relevant libraries or reach out to the community on dev.to or GitHub.

Resources

Remember, building AI-powered bots is an iterative process. Don't be afraid to experiment, learn, and improve your bot over time. Good luck with your project!

Qwik-Todo-DaisyUI-Tailwind-MongoDB-AuthJS-Bun Project

Evgenii Fedotov — Sat, 20 Jan 2024 12:51:53 +0000

Introducing the Qwik-Todo-DaisyUI-Tailwind-MongoDB-AuthJS-Bun Project - ultimate reference point for new Qwik developers. This project showcases a ToDo App, a fundamental and beginner-friendly application for any front-end developer. The source code is openly accessible and serves as an excellent learning tool. It incorporates a modern tech stack including DaisyUI, Tailwind, MongoDB, AuthJS, and Bun, providing valuable insight into how these technologies can be integrated. Dive into the world of Qwik, enhance your skills, and start building your own applications with the help of the Qwik-Todo-DaisyUI-Tailwind-MongoDB-AuthJS-Bun Project.

Project Link: https://github.com/lieranderl/qwik-todo-daisyui-tailwind-mongodb-authjs-bun

Test in action: https://qwik-todo-uphjdpakeq-ew.a.run.app/

Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

Node.js
Bun
MongoDB

Alternatively, you can set up and run code in a devcontainer.

Installation

Clone the repository

git clone https://github.com/lieranderl/qwik-todo-daisyui-tailwind-mongodb-authjs-bun.git

Install packages

bun install

Make env.local file:

AUTH_SECRET:
    xxxxxxxxxxxxxxxxx
GOOGLE_ID:
    xxxxxxxxxxxxxxxxx
GOOGLE_SECRET:
    xxxxxxxxxxxxxxxxx
GITHUB_OAUTH_CLIENT_ID:
    xxxxxxxxxxxxxxxxx
GITHUB_OAUTH_CLIENT_SECRET:
    xxxxxxxxxxxxxxxxx
FACEBOOK_OAUTH_CLIENT_ID:
    xxxxxxxxxxxxxxxxx
FACEBOOK_OAUTH_CLIENT_SECRET:
    xxxxxxxxxxxxxxxxx
MONGO_INITDB_ROOT_USERNAME:
    xxxxxx
MONGO_INITDB_ROOT_PASSWORD:
    xxxxxx
MONGO_DOMAIN:
    xxxxxxxxxxxxx.mongodb.net
MONGO_URI:
    mongodb+srv://$MONGO_INITDB_ROOT_USERNAME:$MONGO_INITDB_ROOT_PASSWORD@$MONGO_DOMAIN/?retryWrites=true&w=majority

Start the server

bun start

Usage

The application allows you to add, delete, update and mark tasks as done. User authentication is handled by AuthJS, sessions stored in MongoDB. The tasks are stored in MongoDB, enabling persistence across sessions. Bun is used as the HTTP server to handle requests and responses.

Built With

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

An Introduction to Qwik-Theme-Toggle Library: A Qwik Component for Theme Switching

Evgenii Fedotov — Fri, 19 Jan 2024 11:28:46 +0000

In the world of web development, user experience takes center stage. The Qwik-Theme-Toggle library, a lightweight and user-friendly Qwik component, allows users to switch between different visual themes, greatly improving the browsing experience. It integrates a theme toggle button into web applications and is compatible with Tailwind CSS and DaisyUI.

What is Qwik-Theme-Toggle Library?

Qwik-Theme-Toggle is a powerful Qwik component developed as a JavaScript library. Its primary purpose is to introduce a theme toggle button in web applications. This button empowers users to smoothly switch between light, dark, and auto modes, thereby significantly improving their browsing experience. The library is designed to be lightweight and user-friendly, ensuring it doesn't impact the performance of your web application.

Compatibility with Tailwind CSS and DaisyUI

A remarkable feature of the Qwik-Theme-Toggle library is its compatibility with Tailwind CSS and DaisyUI, a plugin for Tailwind CSS. This compatibility allows the library to leverage the utility-first CSS framework's flexibility and a robust UI toolkit, facilitating the creation of visually appealing and responsive designs.

Key Features of Qwik-Theme-Toggle Library

The Qwik-Theme-Toggle library offers several compelling features:

Lightweight: The library's lightweight design ensures it does not impact your application's loading speed.
User-Friendly: The theme toggle button is easy to locate and use, providing a smooth user experience.
Versatile: It supports three theme modes - light, dark, and auto. The auto mode adjusts the theme based on the user's system settings.
Qwik Component: As a Qwik component, it integrates seamlessly with applications built using Qwik.
Compatibility: The library is compatible with Tailwind CSS and DaisyUI, facilitating a utility-first approach and the use of a robust UI toolkit.

Installation of Qwik-Theme-Toggle Library

You can install the Qwik-Theme-Toggle library using npm with the following command:

npm install qwik-theme-toggle

If you use Bun, the installation command is:

bun install qwik-theme-toggle

You can find more details about the package on its npm page.

Qwik-Theme-Toggle in Action

You can see the Qwik-Theme-Toggle library in action and experiment with it in this CodeSandbox.

You can also watch this short example video which demonstrates how to use the library in a web application.

How to Use Qwik-Theme-Toggle Library

To utilize the Qwik-Theme-Toggle library, you need to make some additions to your tailwind.config.js file and your HTML file.

The tailwind.config.js file is where you configure your project's Tailwind CSS settings. To use the Qwik-Theme-Toggle library with DaisyUI and Tailwind CSS, you need to make a few modifications to this file.

Here's how you should set up your tailwind.config.js file:

module.exports = {
  content: [
    //...
    "./node_modules/qwik-theme-toggle/**/*.{cjs,mjs}"
  ],
  //..
  darkMode: "class", // for pure Tailwind CSS
  //...
  plugins: [require("daisyui")], // for DaisyUI
}

In the content array, you should include the path to the Qwik-Theme-Toggle library. This ensures Tailwind CSS applies its styling to the library.

The darkMode property should be set to "class" if you're using pure Tailwind CSS. This enables Tailwind's dark mode feature, which Qwik-Theme-Toggle utilizes to switch between light and dark themes.

Lastly, if you're using DaisyUI, you should add the DaisyUI plugin to the plugins array. This lets you use DaisyUI's data-theme attribute with the Qwik-Theme-Toggle library.

Integrating the ThemeScript Component into Your HTML

To start managing the theme of your application right from the document's load, you need to integrate the ThemeScript component into the head section of your HTML file.

Here's how you can do it:

First, import the ThemeScript component from the qwik-theme-toggle library at the top of your file:

//...
import { ThemeScript } from "qwik-theme-toggle";
//...

Then, include the ThemeScript component in the head section of your HTML file. You can customize the component by passing properties to it:

<head>
  //...
  <ThemeScript
    themeStorageKey="theme" // name of the local storage theme key
    themeQuery="theme"      // (Optional) name of the query param to reflect theme
  />
</head>

In the example above, the themeStorageKey property is used to specify the name of the local storage theme key. The themeQuery property (optional) is used to specify the name of the query parameter to reflect the theme in the URL.

Integrating the ThemeToggle Component into Your Code

To integrate the ThemeToggle component into your application import the ThemeToggle component from the qwik-theme-toggle library at the top of your file:

//...
import { ThemeToggle } from "qwik-theme-toggle";
//...

Then, add the ThemeToggle component in your JSX code where you want the theme toggle button to appear. You can customize the component by passing props to it:

<ThemeToggle
  themeStorageKey="theme"           // name of the local storage theme key
  themeQuery="theme"                // (Optional) name of the query param to reflect theme
  textSize="text-2xl"               // Size of the toggle button
  myClass={"hover:text-secondary"}  // Apply a custom class
/>

In the example above, the themeStorageKey and themeQuery props are used to synchronize the theme preference between local storage and the URL query parameter. The textSize prop sets the size of the toggle button, and the myClass prop allows you to apply a custom class to the button.

Contribute and Explore the Qwik-Theme-Toggle Library

For those interested in contributing to the project or want to understand more about how the library works, you can access the source code on its GitHub repository.

The Qwik-Theme-Toggle library consists of three primary files:

theme-script.tsx: This TypeScript file handles the overall theme management. It contains the logic for setting the theme based on the user's selection or system settings, listening for changes to the preferred color scheme using a media query listener, and updating the theme accordingly. It also manages the synchronization of the theme preference between local storage and the URL query parameter. The ThemeScript component is used in the head section of your HTML file to start listening for theme changes as soon as the document is loaded.
theme-toggle.tsx: This TypeScript file handles the theme toggle functionality. It defines the ThemeToggle component which is responsible for managing the theme selection based on the user's choice. It includes the logic for the theme toggle switch and applies the selected theme to the document's root element. The ThemeToggle component is used in your application to listen for theme changes and apply the chosen theme.
themeicon.css: This CSS file provides the styles for the theme toggle button and the associated icons (sun for light mode, moon for dark mode, and a custom auto icon for auto mode). It defines classes for the toggle button and its child elements (sun, moon, auto), and includes a keyframes rule for a rotation animation that's applied to the active icon when the user switches between themes.

Together, these files enable the Qwik-Theme-Toggle library to provide a smooth and visually pleasing theme switching experience for your web application users.

ThemeScript Functionality

The ThemeScript component is responsible for managing the theme selection based on user preference and system settings. Here's a quick overview of what the ThemeScript component is doing:

The ThemeScript component first defines the theme constants - LIGHT, DARK, and AUTO. It then has a setTheme function which applies the selected theme to the document's root element.

It listens for changes to the preferred color scheme using a media query listener and updates the theme accordingly. If the theme is set to AUTO, it will automatically switch between light and dark themes based on the user's system settings.

When the document is loaded, the ThemeScript component checks the local storage for any saved theme preference and applies that theme. It also syncs the theme preference between local storage and the URL query parameter(Optional).

The ThemeScript component is used in the head section of your HTML file to start listening for theme changes as soon as the document is loaded.

ThemeToggle Functionality

The ThemeToggle component is responsible for managing the theme selection based on the user's choice. It handles the theme toggle logic and applies the selected theme to the document's root element. The ThemeToggle component is used in your application to listen for theme changes and apply the chosen theme.

Here's a brief overview of what the ThemeToggle component is doing:

setThemeTailwind: This function applies the selected theme to the document's root element for Tailwind CSS.
setThemeDaisyUI: This function applies the selected theme to the document's root element for DaisyUI.
setThemeQparams: This function sets the theme in the URL query parameters.
handleThemeToggle$: This function is executed when the theme toggle button is clicked. It handles the theme toggle logic based on the current theme mode and applies the chosen theme using the ApplyTheme function.
AutoIcon: This component returns an SVG of the Auto Icon used in the theme toggle button.

ThemeIcon.css Functionality

The ThemeIcon.css file provides the styling for the theme toggle button.

Here is what it does:

.toggle-button: This class applies a smooth transition effect to the toggle button when it is clicked.
.sun, .moon, .auto: These classes position the sun, moon, and auto icons absolutely within the toggle button. They are initially set to be transparent and transition to full opacity when active.
@keyframes rotate: This keyframes rule defines a rotation animation that rotates the active icon from -45 degrees to 0 degrees.
[icon-theme="dark"] .moon, [icon-theme="light"] .sun, [icon-theme="auto"] .auto: These selectors apply the rotation animation to the respective icon when the corresponding theme is active. The CSS classes and animations provide a smooth and visually pleasing transition effect when the user switches between themes.

Conclusion

The Qwik-Theme-Toggle library is a tool that can enhance the user experience of your web application by providing an efficient theme toggle feature. When used in conjunction with Tailwind CSS and DaisyUI, it enables developers to create visually appealing and personalized web applications. If you're developing a web application and want to provide your users with a smooth theme-switching experience, the Qwik-Theme-Toggle library is worth considering.