Forem: Vadim Smirnov

Storybook Starter Guide: Learn Design System Principles

Vadim Smirnov — Fri, 28 Mar 2025 17:44:22 +0000

Run this in your terminal:

npm create storybook@latest

At first glance, it's a generic starter for a component library: a button, a header, and a few example stories. But underneath that simplicity lies something much more powerful — the foundation of a design system.

In this article, we’ll explore how Storybook’s starter is an introduction to core design system principles — reusability, composability, and consistency.

What is Storybook?

Storybook is an open-source tool for building and testing UI components in isolation. Think of it as a dedicated workshop where you can create, preview, and document components in every possible state without spinning up the full application.

But Storybook isn’t just a place to organize your UI components. In practice, it becomes a powerful platform that organizes frontend workflows by:

Letting you build and debug components without business logic getting in the way.
Supporting a wide range of frameworks like React, Vue, Angular, Svelte, and more.
Offering a natural cross-team collaboration workflow — designers, developers, and stakeholders can all review and work on components to deliver great quality user interfaces.

Whether you're crafting a single button or a complete design system, Storybook helps you move faster, stay consistent, and collaborate more effectively.

Benefits of Using Storybook

Now, let's address some more arguments in favor of using Storybook:

Visual Testing of Component States: Each story represents a specific state of a component. This makes it easier to notice edge cases and ensure a consistent look across the application.
Auto-Generated Docs: Autodocs turns your stories into complete, shareable documentation. Anyone on the team can explore usage examples, parameters, and behaviors. This is also a great point when onboarding new team members on the project.
Smooth Collaboration: Designers, product managers, and QA engineers can view and interact with components in the browser, leave feedback, and review changes even without technical knowledge of setting up a local environment.
Works Across Frameworks: Storybook supports React, Vue, Angular, Svelte, Web Components, and more, making it a good option for any team to avoid framework support limitations.
Trusted by Top Companies: The Washington Post, Shopify, NASA, and others rely on Storybook to power their UI workflows. It’s also the foundation behind popular component libraries like Chakra UI or Fluent UI.

Core Design System Principles in the Starter

Reusability

Reusability is a fundamental principle of any design system. It’s about creating abstract components that can be used in different use cases while maintaining a consistent look and feel.

Let's review the included Button component:

export const Button = ({
  primary = false,
  size = 'medium',
  backgroundColor,
  label,
  ...props
}: ButtonProps) => {
  const mode = primary ? 'storybook-button--primary' : 'storybook-button--secondary';
  return (
    <button
      type="button"
      className={['storybook-button', `storybook-button--${size}`, mode].join(' ')}
      style={{ backgroundColor }}
      {...props}
    >
      {label}
    </button>
  );
};

It might look basic, but out of the box, it has a good set of props:

Boolean prop primary to toggle variants
Props for size, color, and label

The stories for this component reinforce reusability:

export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

export const Secondary: Story = {
  args: {
    label: 'Button',
  },
};

export const Large: Story = {
  args: {
    size: 'large',
    label: 'Button',
  },
};

The story format encourages creating components in a Don’t Repeat Yourself (DRY), consistent manner.

Composability

Design systems aren’t just about single-use components — they’re about components that combine like LEGO blocks.

The Header component showcases this principle:

export const Header = ({ user, onLogin, onLogout, onCreateAccount }: HeaderProps) => (
  <header>
    <div className="storybook-header">
      <div>
        <svg width="32" height="32" viewBox="0 0 32 32" xmlns="<http://www.w3.org/2000/svg>">
      ...
        </svg>
        <h1>Acme</h1>
      </div>
      <div>
        {user ? (
          <>
            <span className="welcome">
              Welcome, <b>{user.name}</b>!
            </span>
            <Button size="small" onClick={onLogout} label="Log out" />
          </>
        ) : (
          <>
            <Button size="small" onClick={onLogin} label="Log in" />
            <Button primary size="small" onClick={onCreateAccount} label="Sign up" />
          </>
        )}
      </div>
    </div>
  </header>
);

Here, we don't hardcode buttons that should be present in the header but reuse the existingButton component. This is how good design systems are built — small parts are assembled into larger elements.

Storybook makes it easier to follow this mindset by isolating each component. You focus on one piece at a time.

Consistency

Consistency is key in a design system — visually, behaviorally, and structurally. That can be achieved with design tokens.

The starter doesn’t include an implementation out of the box, but its architecture makes it easy to add one.

For example, at CKEditor, we use a hybrid approach — Syntactically Awesome Style Sheets (Sass) preprocessor and CSS variables:

$radius-medium: var(--app-radius-medium);
$radius-big: var(--app-radius-big);
$radius-bigger: var(--app-radius-bigger);

Then, we can define theme-specific values:

.app-theme-custom {
    --app-radius-medium: 4px;
    --app-radius-big: 7px;
    --app-radius-bigger: 15px;
}

Extending with Addons

One of Storybook’s biggest strengths is its ecosystem of addons. These allow tailoring a Storybook setup for more specific needs, such as testing the accessibility of your components.

With the accessibility addon, accessibility checks can be integrated directly into your component stories.

To enable it, start by installing the npm package:

npm install @storybook/addon-a11y --save-dev

Then register it inside your .storybook/main.js file:

module.exports = {
    addons: [
        ...,
        '@storybook/addon-a11y',
    ],
};

Once set up, every component story gets an Accessibility panel that performs automated audits. It highlights issues like missing labels, contrast problems, and more without leaving your development environment.

This addon serves as a perfect example of how you can extend Storybook beyond the basics.

The full list of available addons can be found on the Storybook Integrations page.

Final Thoughts

In this article, we explored the Storybook starter and its main concepts and features.

It introduces you to the core principles of a good design system:

Reusability
Composability
Consistency

It’s not code that is meant to be removed as soon as generated, but a foundation for your design system. Study, expand, and use it to create a design system that will help you create stunning user interfaces!

How to Detect Bot Traffic using Next.js Middleware: A Quick Guide

Vadim Smirnov — Fri, 28 Feb 2025 15:30:35 +0000

Bots make up a significant portion of internet traffic. Some, like Googlebot, are beneficial, while others — such as scrapers — can harm your site. In this article, we'll explore how to detect and block bots using Next.js Middleware.

What is Bot Detection and Why Does it Matter?

Not all web traffic is human. In fact, almost half of web traffic is automated. Bots can:

Scrape content
Spam your website
Slow down your app

Why Should You Implement Bot Detection?

From a security point of view, bot detection functionality is an essential part of the security toolset.

With bot detection, you can improve security by blocking malicious traffic, reduce server load by filtering unnecessary requests, and protect analytics accuracy by preventing bot traffic.

Since Next.js Middleware runs before a request is processed, it’s the perfect solution for implementing bot detection.

What is Middleware in Next.js?

Middleware in Next.js allows you to run code and execute logic before completing the request.

Additionally, Middleware can be run globally. However, you can modify this behavior for specific routes. It's important to mention that Middleware works really well with platforms like Vercel and Netlify.

How Next.js Middleware Works

Let's simplify the explanation by identifying key facts:

Middleware must be placed in the project root as a middleware.ts or middleware.js file depending if you are using TypeScript or not.
It automatically applies to all routes unless configured otherwise.
It uses the NextResponse to modify requests and perform specific actions like redirecting or rewrite

A Simple Middleware Implementation

Before we add bot detection, let's create a basic Middleware implementation to log requests. First, we need to create middleware.ts in the root directory.

For a basic implementation, our Middleware will do the following:

Log every incoming request in the terminal.
Pass the request through without modification.

import { NextResponse } from "next/server";

const EXCLUDED_PATHS = ["/_next/", "/static/"];
const EXCLUDED_EXTENSIONS = [".svg", ".js", ".css", ".ico", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".woff2"];

export function middleware(req: Request) {
  const url = new URL(req.url);

  if (EXCLUDED_PATHS.some(path => url.pathname.startsWith(path)) || EXCLUDED_EXTENSIONS.some(ext => url.pathname.endsWith(ext))) {
    return NextResponse.next();
  }

  console.log(`Request received: ${req.url}`);
  return NextResponse.next();
}

Now, let's run our Next.js application to verify that our Middleware is functioning as expected.

Start your Next.js app by running the npm run dev in the terminal. Once you visit the localhost:3000 in the browser, check the terminal — you should see the following log there:

Request received: <http://localhost:3000/>

Extend Middleware with Bot Detection

Now, let's improve our Middleware to detect bot-like User-Agents. We can do that by updating middleware.ts with Bot Detection:

import { NextResponse } from "next/server";

const EXCLUDED_PATHS = ["/_next/", "/static/"];
const EXCLUDED_EXTENSIONS = [".svg", ".js", ".css", ".ico", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".woff2"];
const BOT_PATTERNS = [/bot/i, /crawler/i, /spider/i, /curl/i, /wget/i];

export function middleware(req: Request) {
  const url = new URL(req.url);
  const userAgent = req.headers.get("user-agent") || "";

  if (EXCLUDED_PATHS.some(path => url.pathname.startsWith(path)) || EXCLUDED_EXTENSIONS.some(ext => url.pathname.endsWith(ext))) {
    return NextResponse.next();
  }

  if (BOT_PATTERNS.some(pattern => pattern.test(userAgent))) {
    console.log(`Bot detected! (${userAgent}) - Redirecting to /bot-detected.`);
    return NextResponse.redirect(new URL("/bot-detected", req.url));
  }

  console.log(`Request received: ${req.url} | User-Agent: ${userAgent}`);

  return NextResponse.next();
}

Let's review what changed in this version of our Middleware:

We extract the User-Agent header from the request.
Check if it matches one of the bot keywords (bot, crawler, spider, etc.).
Redirect detected bots to /bot-detected.
Log each request’s User-Agent for debugging.

Test the Middleware

Now, let's test our middleware using curl and simulate a bot request. Run the following in your terminal without stopping the Next.js application locally:

curl -i -A "Googlebot" <http://localhost:3000>

If you implemented the Middleware correctly, the following response will be visible in the terminal:

HTTP/1.1 307 Temporary Redirect
location: /bot-detected
Date: Mon, 24 Feb 2025 17:00:34 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked

/bot-detected

As you can see, the bot detection works!

Review of Common Bot Detection Techniques

Now that our basic bot detection Middleware works, let’s explore some common techniques.

User-Agent Header Checking

This is the solution that we implemented as a simple demonstration of bot detection.

It was very straightforward and was great for demo purposes. However, many bots use agents similar to real users, which makes this approach sub-optimal for real-life applications.

IP Address Filtering

This approach can be more effective in filtering and can be applied to real-life, production-ready applications. However, you can't rely on an array of addresses you manually gathered, so you must use anAPI that analyses IP.

That approach offers better protection but may be ineffective for more advanced bots.

Third-Party Bot Detection APIs

Building on the previous approach, if we want enterprise-grade protection, a complete dedicated bot detection service like BotD or DataDome is the most solid means that guarantees high detection accuracy.

While these solutions are not free, they are good enterprise-level solutions for production-ready applications.

If you want to get started with one of the solutions that were mentioned above, Vercel provides starter projects that allow you to see both of them in action:

Conclusion

Bots can have a huge impact on your website, from content scraping and spam to security risks and performance issues. Fortunately, Next.js Middleware provides an efficient way to filter out unwanted traffic before it reaches your app.

While basic bot detection is a great starting point, bots can bypass simple User-Agent checks. If you need stronger protection, consider third-party services like BotD or DataDome to detect even the most advanced bots.

Now, it's time for you to find the optimal solution for your needs!

Create a Rich Text Editor with Astro, Preact & CKEditor 5

Vadim Smirnov — Thu, 06 Feb 2025 12:46:47 +0000

Astro is a modern framework designed for ultra-fast performance by shipping only the JavaScript that's needed. Pair that with Preact, a lightweight alternative to React, and you’ve got the perfect recipe for building fast and efficient applications. To take things a step further, you can integrate CKEditor 5, a powerful rich text editor, to add robust content editing capabilities to your app.

In this article, we’ll walk you through the process of setting up an Astro + Preact project from scratch and show you how to seamlessly integrate CKEditor 5. Let’s dive in!

Why Choose Astro + Preact?

Astro:

Minimal JavaScript by default: Astro ships only what’s necessary to the client.
Perfect for content-focused websites: Ideal for blogs, documentation sites, and other projects where performance matters but also suitable for more complex and dynamic applications.
Framework flexibility: Supports popular frameworks like React, Preact, Vue, Svelte, and Solid.

Preact:

Extremely lightweight: Just ~3 kB gzipped, making it an excellent choice for performance-conscious projects.
React ecosystem compatibility: Most React libraries work seamlessly with Preact.
Fast and efficient: A great way to build modern, fast applications.

By combining Astro’s performance-first approach with Preact’s lightweight design, you get the best of both worlds: a highly-performant app and a pleasant developer experience.

Why CKEditor?

CKEditor is a powerful, flexible, rich text editor that enhances content creation and collaboration.

Fast & Efficient: Great writing experience with autoformatting, merge fields, and text transformation.
Complete Toolset for Collaboration: Real-time co-editing, track changes, and comments.
Flexible & Customizable: Over 100 plugins are configurable toolbar are available with CKEditor

Integrating CKEditor into Astro + Preact starter will allow you to build complex applications with excellent performance and feature-rich editing experience for various use cases.

Setting Up Your Astro + Preact Project

Here’s how to go from zero to a fully functional Astro + Preact project with CKEditor 5.

Step 1: Create a New Astro Project

First, let’s create a fresh Astro project. Open your terminal and run:

npm create astro@latest

Follow the CLI’s prompts to set up your project. Astro’s installation process is straightforward and beginner-friendly.

Step 2: Add Preact to Your Astro Project

Once your Astro project is set up, it’s time to integrate Preact. Astro provides a simple way to add Preact to your project:

npx astro add preact

This command automatically updates your configuration files and installs the necessary dependencies. With just one command, Preact is ready to go!

Step 3: Generate Your CKEditor Code

CKEditor 5 is a flexible and customizable rich text editor. To add it to your project, use the CKEditor 5 Builder. Here’s how:

Select the preset: Start with the Classic Editor (starter) for a simple yet powerful editor.
Enable features: CKEditor offers over 100 plugins. Pick the features you need (e.g., bold, italic, link) and decide between free or premium options.
Configure the toolbar: Customize the toolbar layout to match your requirements.
Generate code snippets: Choose React as the technology and Cloud (CDN) as the integration method. If you’ve selected only free features, your code snippet will include a 24-hour evaluation key; alternatively, press the Sign up for trial button to create a license key and automatically propagate it in your code snippets. If you have issues, refer to License key set up documentation.

Step 4: Integrate CKEditor 5 into Your Project

Now let’s integrate CKEditor 5 into your Astro + Preact project.

1. Install CKEditor’s React Package

Install CKEditor’s React package using npm:

npm install @ckeditor/ckeditor5-react

2. Add CKEditor Styles

Create a styles folder in your project and add a file named App.css. Paste the styles provided by the CKEditor Builder into this file:

@import url('<https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;1,400;1,700&display=swap>');

@media print {
    body {
        margin: 0 !important;
    }
}

.main-container {
    font-family: 'Lato';
    width: fit-content;
    margin-left: auto;
    margin-right: auto;
}

.ck-content {
    font-family: 'Lato';
    line-height: 1.6;
    word-break: break-word;
}

.editor-container_classic-editor .editor-container__editor {
    min-width: 795px;
    max-width: 795px;
}

3. Create an Editor Component

Create a file named editor.jsx in the components folder. Here’s the component code, slightly modified for Preact:

import { useState, useEffect, useRef, useMemo } from 'preact/hooks';
import { CKEditor } from '@ckeditor/ckeditor5-react';
import './App.css';

const LICENSE_KEY = 'YOUR_LICENSE_KEY_HERE';

export default function Editor() {
    const editorContainerRef = useRef(null);
    const editorRef = useRef(null);
    const [isLayoutReady, setIsLayoutReady] = useState(false);
    const cloud = useCKEditorCloud({ version: '44.1.0' });

    useEffect(() => {
        setIsLayoutReady(true);

        return () => setIsLayoutReady(false);
    }, []);

    const { ClassicEditor, editorConfig } = useMemo(() => {
        if (cloud.status !== 'success' || !isLayoutReady) {
            return {};
        }

        const { ClassicEditor, AutoLink, Autosave, Bold, Essentials, Italic, Link, Paragraph } = cloud.CKEditor;

        return {
            ClassicEditor,
            editorConfig: {
                toolbar: {
                    items: ['bold', 'italic', '|', 'link'],
                    shouldNotGroupWhenFull: false
                },
                plugins: [AutoLink, Autosave, Bold, Essentials, Italic, Link, Paragraph],
                initialData:
                    '<h2>Evaluation license key 🔑</h2>\\\\n<p>\\\\n\\\\tAn evaluation key is being used in this editor. <a href="<https://portal.ckeditor.com/checkout?plan=free>">\\\\n\\\\t\\\\tCreate an account to use your own license keys.\\\\n\\\\t</a>\\\\n</p>\\\\n\\\\n<h2>Congratulations on setting up CKEditor 5! 🎉</h2>\\\\n<p>\\\\n\\\\tYou\\\\'ve successfully created a CKEditor 5 project. This powerful text editor\\\\n\\\\twill enhance your application, enabling rich text editing capabilities that\\\\n\\\\tare customizable and easy to use.\\\\n</p>\\\\n<h3>What\\\\'s next?</h3>\\\\n<ol>\\\\n\\\\t<li>\\\\n\\\\t\\\\t<strong>Integrate into your app</strong>: time to bring the editing into\\\\n\\\\t\\\\tyour application. Take the code you created and add to your application.\\\\n\\\\t</li>\\\\n\\\\t<li>\\\\n\\\\t\\\\t<strong>Explore features:</strong> Experiment with different plugins and\\\\n\\\\t\\\\ttoolbar options to discover what works best for your needs.\\\\n\\\\t</li>\\\\n\\\\t<li>\\\\n\\\\t\\\\t<strong>Customize your editor:</strong> Tailor the editor\\\\'s\\\\n\\\\t\\\\tconfiguration to match your application\\\\'s style and requirements. Or\\\\n\\\\t\\\\teven write your plugin!\\\\n\\\\t</li>\\\\n</ol>\\\\n<p>\\\\n\\\\tKeep experimenting, and don\\\\'t hesitate to push the boundaries of what you\\\\n\\\\tcan achieve with CKEditor 5. Your feedback is invaluable to us as we strive\\\\n\\\\tto improve and evolve. Happy editing!\\\\n</p>\\\\n<h3>Helpful resources</h3>\\\\n<ul>\\\\n\\\\t<li>📝 <a href="<https://portal.ckeditor.com/checkout?plan=free>">Trial sign up</a>,</li>\\\\n\\\\t<li>📕 <a href="<https://ckeditor.com/docs/ckeditor5/latest/installation/index.html>">Documentation</a>,</li>\\\\n\\\\t<li>⭐️ <a href="<https://github.com/ckeditor/ckeditor5>">GitHub</a> (star us if you can!),</li>\\\\n\\\\t<li>🏠 <a href="<https://ckeditor.com>">CKEditor Homepage</a>,</li>\\\\n\\\\t<li>🧑‍💻 <a href="<https://ckeditor.com/ckeditor-5/demo/>">CKEditor 5 Demos</a>,</li>\\\\n</ul>\\\\n<h3>Need help?</h3>\\\\n<p>\\\\n\\\\tSee this text, but the editor is not starting up? Check the browser\\\\'s\\\\n\\\\tconsole for clues and guidance. It may be related to an incorrect license\\\\n\\\\tkey if you use premium features or another feature-related requirement. If\\\\n\\\\tyou cannot make it work, file a GitHub issue, and we will help as soon as\\\\n\\\\tpossible!\\\\n</p>\\\\n',
                licenseKey: LICENSE_KEY,
                placeholder: 'Type or paste your content here!'
            }
        };
    }, [cloud, isLayoutReady]);

    return (
        <div className="main-container">
            <div className="editor-container editor-container_classic-editor" ref={editorContainerRef}>
                <div className="editor-container__editor">
                    <div ref={editorRef}>{ClassicEditor && editorConfig && <CKEditor editor={ClassicEditor} config={editorConfig} />}</div>
                </div>
            </div>
        </div>
    );
}

Step 5: Adjust Astro for Preact Compatibility

To make React libraries (like CKEditor 5 integration package) work in a Preact environment, update your astro.config.mjs file as follows:

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';

export default defineConfig({
  integrations: [preact()],
  vite: {
    resolve: {
      alias: {
        react: 'preact/compat',
        'react-dom': 'preact/compat',
      },
    },
  },
});

Step 6: Add the Editor to Your Page

Finally, import the Editor component in your Astro page and render it using the client:only="preact" directive:

---
import Layout from '../layouts/Layout.astro';
import Editor from '../components/editor';
---

<Layout>
  <Editor client:only="preact" />
</Layout>

Once completed, you will be able to see the editor on the page:

Wrapping Up

Congratulations! You’ve successfully set up an Astro + Preact project and integrated CKEditor 5 into it. Here’s a quick recap of the key benefits of the created setup:

Minimal JavaScript Thanks to Preact: Preact keeps your application lightweight by reducing the shipped JavaScript, resulting in faster load times and improved performance, especially on content-focused websites.
Powerful React Compatibility: Since Preact is compatible with most React libraries and components, you can easily integrate React libraries while benefiting from Preact’s smaller footprint.
Great Developer Experience: Astro’s flexibility and Preact’s simplicity allow for a scalable setup with reusable components, making development more efficient and easier to maintain.
Powerful Editing Tool: CKEditor 5 enhances content creation with rich text formatting, real-time collaboration, media embedding, and an extensive plugin ecosystem, giving users a professional-grade editing experience.

This setup offers incredible performance while maintaining a great developer experience.

If you’d like to extend your CKEditor setup, check out the following resources:

CKEditor demo pages to get inspiration
CKEditor 5 features to get a high-level understanding of what is available with CKEditor
CKEditor Documentation to go deeper and see how you can customize not only the editor setup but also the plugin's behavior

Let us know in the comments what plugins or configurations you’ve used! 🚀

Building a Measuring Tool with the Resize Observer API

Vadim Smirnov — Fri, 20 Dec 2024 18:03:45 +0000

Web APIs - a very interesting and rarely well explored territory. And yet, there's a large number of unique and very useful APIs that can help you to create tools for your projects.

For example, tracking size changes is key to creating dynamic, responsive experiences. This is where the Resize Observer API comes in.

In this article, we’ll build a measuring tool that displays the width and height of a resizable box in real-time. This is a project that demonstrates the power of the Resize Observer API and Browser APIs in general in a practical and interactive way.

What is the Resize Observer API?

The Resize Observer API is a browser feature that allows you to detect changes to the size of an element. Resize Observer works on individual elements. It works out-of-the-box, and can be a great addition to your toolset for building responsive design and dynamic UIs.

Here’s what makes it great:

It’s lightweight and easy to use
You can track changes in size for specific elements, not just the entire viewport
It’s perfect for building responsive components or resizable widgets

What We’re Building

We’ll create a resizable box with dimensions displayed inside of it. As the user resizes the box, the displayed dimensions will update in real time.

Step 1: Setting Up the Project

First, let’s set up the basic structure for our project:

resize-tool/
├── index.html
├── styles.css
├── script.js

Step 2: The Markup

Here’s a simple layout for our app. The resizable box includes a text span to display its dimensions:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Measuring Tool with Resize Observer API</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
  <div class="container">
    <div id="resizableBox" class="resizable">
      <span id="dimensions">Width: 0px, Height: 0px</span>
    </div>
  </div>
  <script src="script.js"></script>
</body>
</html>

Step 3: Styling the App

We’ll add some styles to make the resizable box more visually appealing:

body {
  font-family: Arial, sans-serif;
  margin: 0;
  padding: 0;
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
  background: #f0f0f0;
}

.container {
  position: relative;
  width: 80%;
  height: 80%;
}

.resizable {
  position: absolute;
  width: 300px;
  height: 200px;
  border: 2px dashed #007bff;
  background: rgba(0, 123, 255, 0.1);
  display: flex;
  justify-content: center;
  align-items: center;
  resize: both;
  overflow: auto;
}

 .resizable span {
  background: white;
  padding: 5px;
  border-radius: 4px;
  font-size: 20px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

Step 4: Adding Real-Time Resize Tracking

Now let’s bring the project to life using the Resize Observer API:

const resizableBox = document.getElementById('resizableBox');
const dimensions = document.getElementById('dimensions');

const resizeObserver = new ResizeObserver(entries => {
  for (let entry of entries) {
    const { inlineSize: width, blockSize: height } = entry.borderBoxSize[0];
    dimensions.textContent = `Width: ${Math.round(width)}px, Height: ${Math.round(height)}px`;
  }
});

resizeObserver.observe(resizableBox);

Step 5: Testing the Tool

Open the index.html file in your browser.
Drag the corners of the box to resize it.
Watch as the dimensions update instantly!

How It Works

The Resize Observer API is initialized to monitor size changes for the resizableBox element. It triggers a callback whenever the size of the observed element changes.
The Resize Observer Entry provides updated dimensions through the borderBoxSize property.
The updated width and height values are extracted and displayed dynamically by modifying the text content of the <span> element inside the resizable box.

Conclusion

In this tutorial, we built a fun and interactive measuring tool using the Resize Observer API. This project demonstrates how browser APIs can simplify complex tasks.
If you try this out or extend it further, feel free to share your creations in the comments!
Also, check out the CKEditor blog for articles around rich-text editors, and start your journey with CKEditor 5 by signing up for a free trial today!

📝 🚀 Creating our first documentation from scratch using Astro and Refact AI coding assistant

Vadim Smirnov — Mon, 18 Sep 2023 17:36:16 +0000

At Refact, we put performance and developer experience as our top priority. That's why we were looking for a lightweight and highly customizable template for our documentation.

Previously, we used Astro for our refact.ai website and wanted to stay within the Astro ecosystem for the documentation.

Let's see how easy it will be to build the docs using the Starlight template from Astro with the help of the Refact AI coding assistant.

Refact: Open-source AI coding assistant

Just a quick background about us: Refact is an open-source AI coding assistant that can significantly boost developer productivity with tools like code completion, code refactoring, and chat.

Building the Starlight docs

Starlight is a framework-agnostic Astro template for building documentation websites. With a straightforward configuration process and the support of Markdown and MDX, you get a solid foundation for your documentation.

In this article, we will follow the manual setup process to get a better understanding of all of the parts that are required for Starlight to work.

Creating an Astro project

First, we must create an Astro project as a foundation since Starlight is built on top of Astro.

To do that, we need to run the following command in your terminal:



npm create astro@latest

You can pick the option with the sample files.

Once the setup process is completed, you can run npm run dev in your terminal and see a starter template in your browser.

With Astro, you get an extremely straightforward structure of the project:



/
├── public/
│   └── favicon.svg
├── src/
│   ├── components/
│   │   └── Card.astro
│   ├── layouts/
│   │   └── Layout.astro
│   └── pages/
│       └── index.astro
└── astro.config.mjs

Adding Starlight

Now that we have the foundation, we are ready to add Starlight to turn our website into a fully functional documentation.

To do that, run the following command in your terminal:



npx astro add starlight

After completing the multistep installation process in your terminal, we can see that our Astro configuration file was updated.



import { defineConfig } from 'astro/config';

+ import starlight from "@astrojs/starlight";

export default defineConfig({
+   integrations: [starlight()]
});

Perfect! Now, we have an Astro project with a Starlight integration.

Configuring Starlight

Even though we installed the Starlight integration, we need to complete three more steps to see it working:

We need to configure the plugin
The next step will be a content collection configuration
And last but not least, we need to add markdown files to see the complete documentation

This process is very straightforward, but Refact will help us to boost the configuration process with the autocomplete functionality.

First, let's configure the plugin. Starlight allows you to set many things in the configuration, but only one property is required for the plugin to function, which is a title.

In your astro.config.mjs file, you should add a title inside the Starlight integration. Refact immediately starts to help you with that!



import { defineConfig } from 'astro/config';

import starlight from "@astrojs/starlight";

export default defineConfig({
    integrations: [starlight(
+       {
+           title: "My awesome documentation"
+       }
    )]
});

The next step is to configure the content collection. The content collection allows us to handle the dynamic generation of pages from markdown files.

To configure the content collection, we need to complete the following steps:

Create a folder structure for the documentation
Create the config file and define the collection with the docs schema

For documentation to function, we need to create a content folder inside the src directory, which will be the root directory for the documentation-specific files.

Inside that folder, we need to create the config.ts file to define the collection.

First, let's import two functions that we will use - defineCollection and doscSchema.



+ import { defineCollection } from 'astro:content'
+ import { docsSchema } from '@astrojs/starlight/schema'

Now, we are ready to define the collection. Refact will pick it up and help you to complete that logic, which speeds up the process for you and helps you with guidance on what needs to be completed

When the configuration process is completed, let's add content to see the documentation in action.

Inside the content folder, we need to add the docs directory. There, we should add an index.md file with the following structure:



---
title: "My Documentation"
description: "This is a getting started guide of my documentation."
---

This is the first segment of my documentation!

If we start the project locally, we will see our beautiful documentation functioning as expected!

Customizing your documentation

The results that we achieved are great, but it looks very generic. That's why Starlight allows you to customize the documentation and make it more personalized.

Let's modify the frontmatter in index.md file to turn it into a landing page of your documentation. Plenty of options are available for you to make a great-looking landing page. At Refact, we used the following:

template - allows you to turn a regular documentation page into a landing page
hero - an option with tagline, image, and actions properties to generate a hero banner

In addition to that, Starlight comes with components that allow you to add more code to the landing page.

Don't forget to change your index.md to index.mdx for components to work!

As a final result, here's how the code for the landing page might look:



---
title: Welcome to Refact Documentation!
description: Refact is a powerful AI coding assistant that combines completion, refactoring, chat, and more.
template: splash
hero:
  tagline: Refact is a powerful AI coding assistant that combines completion, refactoring, chat, and more.
  image:
    file: ../../assets/refact.png
  actions:
    - text: Get started
      link: /getting-started/what-is-refact/
      icon: right-arrow
      variant: primary
    - text: VS Code Extension
      link: <https://marketplace.visualstudio.com/items?itemName=smallcloud.codify>
    - text: Jetbrains Plugin
      link: <https://plugins.jetbrains.com/plugin/20647-codify>
---

import { Card, CardGrid } from '@astrojs/starlight/components';

## Features

<CardGrid stagger>
    <Card title="Code Completion" icon="pencil">
        As you write code, Refact suggests potential code completions based on the context of your code,
    looking up and down. It can suggest whole functions, classes, commonly used programming patterns,
    libraries, and APIs usage.
    </Card>
    <Card title="Improve code" icon="magnifier">
        Refact can identify code that could be refactored to be more efficient or easier to understand.
    It can also detect bugs in your code and generate patches to fix them.
    </Card>
    <Card title="AI Chat" icon="rocket">
        Use plain language prompts in Refact chat to ask questions or get help with
    writing code without leaving your IDE.
    </Card>
    <Card title="Transform and analyze code" icon="setting">
        Refact can analyze the complexity of your code and explain unclear lines of code.
    It can also transform your code into a different language.
    </Card>
</CardGrid>

The following code generated a great-looking landing page with lots of helpful content.

Changing the color theme

As you saw in the screenshot, the color theme we use for the Refact documentation differs from the one available out of the box. Starlight makes it very straightforward to change the color scheme.

Starlight allows you to add custom styles to match the documentation colors with colors that represent your brand.

First, we must create a custom.css file in the src/styles folder. After that, we must link that file to the astro.config.mjs file.



import { defineConfig } from 'astro/config';

import starlight from "@astrojs/starlight";

export default defineConfig({
    integrations: [Starlight (
        {
            title: "My awesome documentation",
+           customCss: [
+               './src/styles/custom.css'
+           ]
        }
    )
    ]
});

You can modify the color theme in your newly created CSS file. Here is an example of styles that we use at Refact to match our brand colors:



/* Dark mode colors. */
:root {
--sl-color-accent-low: #42100e;
--sl-color-accent: #c70016;
--sl-color-accent-high: #f8b6ad;
--sl-color-white: #ffffff;
--sl-color-gray-1: #eeeeee;
--sl-color-gray-2: #c2c2c2;
--sl-color-gray-3: #8b8b8b;
--sl-color-gray-4: #585858;
--sl-color-gray-5: #383838;
--sl-color-gray-6: #272727;
--sl-color-black: #181818;
}

/* Light mode colors. */
:root[data-theme='light'] {
--sl-color-accent-low: #fcc9c2;
--sl-color-accent: #cb0017;
--sl-color-accent-high: #610b0c;
--sl-color-white: #181818;
--sl-color-gray-1: #272727;
--sl-color-gray-2: #383838;
--sl-color-gray-3: #585858;
--sl-color-gray-4: #8b8b8b;
--sl-color-gray-5: #c2c2c2;
--sl-color-gray-6: #eeeeee;
--sl-color-gray-7: #f6f6f6;
--sl-color-black: #ffffff;
}

If you refresh the page, you can see that the color theme was updated!

Conclusion

And there we have it!
We've explored the Starlight project - a fantastic solution for the documentation, and we used Refact - an AI coding assistant that immediately picked up our project's context and helped us get used to an unfamiliar code base a lot faster.

Next Steps

With a solid foundation and an incredible AI ally, you can explore the Starlight project to see how to personalize and make your documentation stunning.
In addition, I encourage you to try Refact and see how it will improve your productivity and help you become more efficient as an engineer.

Join our Discord server if you need assistance from the Refact team and community to get started faster!

Nhost CLI: From Zero to Production

Vadim Smirnov — Fri, 18 Feb 2022 13:20:58 +0000

In the previous tutorials, that are covered in the documentation, we tested various parts of Nhost, such as:

Database
GraphQL API
Permission
JavaScript SDK
Authentication

All changes we did to our database and API happened directly in the production of our Nhost app.

It’s not ideal for making changes in production because you might break things, which will affect all users of your app.

Instead, it’s recommended to make changes and test your app locally before deploying those changes to production.

To do changes locally, we need to have a complete Nhost app running locally, which the Nhost CLI does.

The Nhost CLI matches your production application in a local environment, this way you can make changes and test your code before deploying your changes to production.

Recommended workflow with Nhost

Develop locally using the Nhost CLI.
Push changes to GitHub.
Nhost automatically applies changes to production.

What you’ll learn in this guide:

Use the Nhost CLI to create a local environment
Connect a GitHub repository with a Nhost app
Deploy local changes to production

Setup the recommended workflow with Nhost

What follows is a detailed tutorial on how you setup Nhost for this workflow

Create Nhost App

Create a new Nhost app for this tutorial.

It’s important that you create a new Nhost app for this guide instead of reusing an old Nhost app because we want to start with a clean Nhost app.

Create new GitHub Repository

Create a new GitHub repository for your new Nhost app. The repo can be both private or public.

Connect GitHub Repository to Nhost App

In the Nhost Console, go to the dashboard of your Nhost app and click Connect to GitHub.

Install the Nhost CLI

Install the Nhost CLI using the following command:



sudo curl -L https://raw.githubusercontent.com/nhost/cli/main/get.sh | bash

Initialize a new Nhost App locally:



nhost init -n "nhost-example-app" && cd nhost-example-app

And initialize the GitHub repository in the same folder:



echo "# nhost-example-app" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/[github-username]/nhost-example-app.git
git push -u origin main

Now go back to the Nhost Console and click Deployments. You just made a new deployment to your Nhost app!

If you click on the deployment you can see that nothing was really deployed. That’s because we just made a change to the README file.

Let’s do some backend changes!

Local changes

Start Nhost locally:



nhost dev

💡 Make sure you have Docker installed on your computer. It’s required for Nhost to work.

The nhost dev command will automatically start a complete Nhost environment locally on your computer using:

Postgres
Hasura
Authentication
Storage
Serverless Functions
Mailhog

You use this local environment to do changes and testing before you deploy your changes to production.

Running nhost dev also starts the Hasura Console.

💡 It’s important that you use the Hasura Console that is started automatically when you do changes. This way, changes are automatically tracked for you.

In the Hasura Console, create a new table customers with two columns:

id
name

When we created the customers table there was also a migration created automatically. The migration was created at under nhost/migrations/default.



$ ls -la nhost/migrations/default
total 0
drwxr-xr-x  3 eli  staff   96 Feb  7 16:19 .
drwxr-xr-x  3 eli  staff   96 Feb  7 16:19 ..
drwxr-xr-x  4 eli  staff  128 Feb  7 16:19 1644247179684_create_table_public_customers

This database migration has only been applied locally, meaning, you created the customers table locally but it does not (yet) exists in production.

To apply the local change to production we need to commit the changes and push it to GitHub. Nhost will then automatically pick up the change in the repository and apply the changes.

💡 You can commit and push files in another terminal while still having nhost dev running.



git add -A
git commit -m "Initialized Nhost and added a customers table"
git push

Head over to the Deployments tab in the Nhost console to see the deployment.

Once the deployment finishes the customers table is created in production.

We’ve now completed the recommended workflow with Nhost:

Develop locally using the Nhost CLI.
Push changes to GitHub.
Nhost deploys changes to production.

Apply metadata and Serverless Functions

In the previous section, we only created a new table; customers. Using the CLI you can also do changes to other parts of your backend.

There are three things the CLI and the GitHub integration track and applies to production:

Database migrations
Hasura Metadata
Serverless Functions

For this section, let’s do one change to the Hasura metadata and create one serverless function

Hasura Metadata

We’ll add permissions to the users table, making sure users can only see their own data. For this, go to the auth schema and click on the users table. then click on Permissions and enter a new role user and create a new select permission for that role*.*

Create the permission with custom check:



{
  "id": {
    "_eq" : "X-Hasura-User-Id"
  }
}

Select the following columns:

id
created_at
display_name
avatar_url
email

Then click Save permissions.

Now, let’s do a git status again to confirm the permission changes we did were tracked locally in your git repository.

We can now commit this change:



git add -A
git commit -m "added permission for uses"

Now let’s create a serverless function before we push all changes to GitHub so Nhost can deploy our changes.

Serverless Function

A serverless function is a piece of code written in JavaScript or TypeScript that takes an HTTP request and returns a response.

Here’s an example:



import { Request, Response } from 'express'

export default (req: Request, res: Response) => {
  res.status(200).send(`Hello ${req.query.name}!`)
}

Serverless functions are placed in the functions/ folder of your repository. Every file will become its own endpoint.

Before we create our serverless function we’ll install express, which is a requirement for serverless functions to work.



npm install express
# or with yarn
yarn add express

We’ll use TypeScript so we’ll install two type definitions too:



npm install -d @types/node @types/express
# or with yarn
yarn add -D @types/node @types/express

Then we’ll create a file functions/time.ts

In the file time.ts we’ll add the following code to create our serverless function:



import { Request, Response } from 'express';

export default (req: Request, res: Response) => {
  return res
    .status(200)
    .send(`Hello ${req.query.name}! It's now: ${new Date().toUTCString()}`);
};

We can now test the function locally. Locally, the backend URL is http://localhost:1337. Functions are under /v1/functions. And every function’s path and filename becomes an API endpoint.

This means our function functions/time.ts is at http://localhost:1337/v1/functions/time.

Let’s use curl to test our new function:



curl http://localhost:1337/v1/functions/time
Hello undefined! It's now: Sun, 06 Feb 2022 17:44:45 GMT

And with a query parameter with our name:



curl http://localhost:1337/v1/functions/time\?name\=Johan
Hello Johan! It's now: Sun, 06 Feb 2022 17:44:48 GMT

Again, let’s use git status to see the changes we did to create our serverless function.

Now let’s commit the changes and push them to GitHub.



git add -A
git commit -m "added serverless function"
git push

In the Nhost Console, click on the new deployment to see details

After Nhost has finished deploying your changes we can test them in production. First let’s confirm that the user permissions are applied.

Then, let’s confirm that the serverless function was deployed. Again, we’ll use curl:



curl https://your-backend-url.nhost.run/v1/functions/time\?name\=Johan

Conclusion

In this tutorial, we have installed the Nhost CLI and created a local Nhost environment to do local development and testing.

In the local environment, we’ve made changes to our database, to Hasura’s metadata, and created a serverless function.

We’ve connected a GitHub repository and pushed our changes to GitHub.

We’ve seen Nhost automatically deploying our changes and we’ve verified that the changes were applied.

In summary, we’ve set up a productive environment using the recommended Nhost workflow:

Develop locally using the Nhost CLI.
Push changes to GitHub.
Nhost deploys changes to production.

In addition to all that, the Nhost team is always happy to support you with any questions you might have on Discord and Github!

Hacktober 2021 results

Vadim Smirnov — Mon, 01 Nov 2021 19:19:40 +0000

With Hacktober coming to an end, we would like to take a moment to appreciate the overwhelming support and contributions we've seen the past month. It was our debut in this year's fest, and we feel like we've kicked the door in with our powerful community.

Hacktober 2021 community achievements

We are incredibly humbled by the participation of so many new and existing community members over this past month. As a young company, it is incredible to see how old, more experienced community members helped guide new ones getting started while others teamed up to find solutions and helped extend the plugin suite of Medusa.

In the end, the effort led to the production of almost 100 pull requests and three new plugins. Likewise, many new developers joined our community, and we are excited to see you build more with Medusa in the future.

A quick glimpse of the results achieved during this October:

~100% new Discord members
64 merged pull requests
21 pull requests in review

Plugins in development:

Strapi
Algolia
Elastic
ShipBob

We are grateful for all your contributions!

Time to give back

Swag. As described in the Hacktoberfest announcement article, every contributor will receive special Medusa swag as an appreciation gift. Our small token of gratitude to all of you that took the time to participate in the Hacktober. The send-outs will happen during November - we cannot wait to send them out.

Wall of appreciation. Our website will soon feature a wall of appreciation displaying all Medusa contributors. There is no fix or feature too small for this wall, so no reason to hold back if you want to see yourself in there.

Community chat. At last, we wanted to invite you all to an in-person Zoom chat on Friday the 5th of November. Here we will gladly welcome everyone from our community to a chat about commerce, Medusa, and all things community-related. For more info, please follow along in our Discord during the following days.

There is still an opportunity to be involved in Medusa development

The opportunity to contribute and get involved in the development process of Medusa is not limited to Hacktoberfest. We will keep welcoming new community members just as we've done the past month. You can follow our contribution guide to get started.

We strive to always have issues that are up for grabs so that everyone can take part. If you have your ideas or feature requests, you can find the entire Medusa team on our Discord server.

Hope to see you there!

That one thing I regret about my CSS code

Vadim Smirnov — Sun, 10 Oct 2021 17:58:55 +0000

The tech world evolves in a tremendously fast manner, and so do design trends. When teams are working hard to deliver beautiful applications, they are making sure that expectations meet reality.

While doing that, engineers have to work with default browser behavior like the topic of this article - outline.

When trying to deliver a great user experience, it's easy to get distracted and start paying less attention to details and not realizing why these default elements are implemented in the first place.

I was this engineer, and the goal of this article is to raise awareness around accessibility and explain that you should keep the outline for your projects even if it doesn't fit the look and feel of your application.

What is an `outline`?

As the name implies, the outline is an outside line around the HTML element.

The first look feels pretty close to a border property, but there are some essential differences in technical aspects and in mindset in general.

The outline is not visible if the element is not focused. The idea behind this property is to indicate that the component can be focused on folks using the keyboard only to navigate through your application or have a visual impairment.

Some of the technical differences between outline and border are:

you can not modify the edges of the outline . it operates as a single unit
outline does not take any space and does not affect other elements and layout in general

For more information, you can check the MDN spec about the outline.

Why should outline stay?

The outline has a very simple look and doesn't fit most of the modern minimalistic design concepts. That's why you can quite often find that engineers write a set of styles to hide it and keep the indication that the element is clickable.

.my-fancy-looking-button {
    outline: none; /* Hide the outline */
    cursor: pointer; /* Add the pointing cursor when hovering the element */
}

From the first look, that might feel like a valid solution, but the reality is that it's not.

When hiding the outline, you have a couple of adverse outcomes, the accessibility of your application gets worst, and navigation with keyboard only is getting trickier.

Accessibility issue

Different groups of users need the outline to understand how they can navigate through your website.

We all are different, and a good project should aim to be accessible for everyone. In my honest opinion, a project with great attention to accessibility is better than a minimalistic clean-looking application that is convenient for a specific user group only.

I deliberately didn't use the phrase "sacrificing the great design for the best" because making an application more accessible is never a sacrifice.

Caring about people should never be a negative aspect!

Keyboard navigation issue

Many users prefer to navigate through websites quickly. An outline is a fantastic feature that can help with that.

Creators want their applications to look beautiful, but sadly, it affects how specific projects help solve some problems quickly and conveniently.

Here you can find a gif that shows the navigation using the Tab key.

What if you still want to remove an outline?

I believe that this should not be an option, but if you still decide to remove an outline, there is an accessible way of doing that.

Steve Faulkner's article covers the way of removing the outline and keeping your application accessible.

Suppose you are ready to add a third-party library to your application. In that case, you can use the remove-focus-outline npm package created by Lindsay Evans, which implements the idea described in the article.

Conclusion

This topic is not new, and I am happy if it is not needed since your application is accessible for different users. Sadly I still can see engineers sacrificing accessibility for an excellent design. That's why I decided to give some attention to a topic that can help you build projects that can help more users find it useful.

I was an engineer who was not paying attention to this specific point, and hopefully, this article can help more people to improve their applications.

Keep the great work, and stay tuned!

Medusa Hacktoberfest 2021

Vadim Smirnov — Thu, 30 Sep 2021 17:07:14 +0000

It's that time of year, and Hacktober is right around the corner. This year Medusa is excited to take part in the fest for the first time.

An excellent opportunity to learn more about the open-source environment, meet creators, active contributors and win a t-shirt or have a tree planted in your name!

Every year Hacktober fest brings tremendous activity and helps the open-source ecosystem grow.

What is Hacktober?

Hacktober fest is a worldwide event that Digital Ocean organizes with the primary goal of supporting the open-source culture by encouraging contributions to open-source projects participating in the event.

Making four or more contributions between October 1-31 will allow you to get a memorable t-shirt as a token of appreciation, or you can choose to have a tree planted in your name and help make Hacktoberfest 2021 more carbon neutral.

You can follow this guide to get a grasp of the rules.

Why contribute to Medusa?

Medusa is a headless e-commerce engine with a mission to provide a fantastic developer experience and give merchant's full control of their ecommerce stack.

By contributing to Medusa, you help push the boundaries of e-commerce and make amazing commerce experiences easier for developers to create.

By actively participating in Hacktober fest, you make Medusa more sustainable and help us progress quickly. Every single contribution matters, and you'll get an appreciation gift for your time and effort:

One pull request → Medusa sticker
Three pull requests → Medusa t-shirt
Build a Plugin (issues labeled with plugin) → Complete Medusa pack (t-shirt, hoodie, sticker)

How can I contribute?

Medusa supplies developers with different open-source tools, which you can find on our Github profile. Pick the tool you like the most and follow our contribution guide to keep the consistency of deliveries.

Contributing to an open-source project might feel intimidating at the beginning, and below, you can find a guide about the process:

Browse the issues that are labeled hacktober
After finding an issue you want to take over, you can let the community know that you are willing to provide a solution in the comments section.
Fork the Medusa repo and create a branch for your solution according to the workflow described in the contribution guide.
When the functionality is reviewed, push the branch to the forked repo and submit a pull request.
After that, the Medusa core team members will review the pull request and let you know if additional work is needed.
Once you receive the approval from the team, the contribution is ready to be merged and taken into account for the overall Hacktober fest activity.

For more detailed guidance and support, feel free to join our Discord to ask the engineering team directly.

Where do I find help from the Medusa community?

The community has a massive priority for Medusa.

Contributing to an open-source project might be confusing and complicated. That's why team members of Medusa are always ready to support you on this path.

Feel free to join our Discord and chat directly with the engineering team, so you can get the warm, welcoming experience and be surrounded by passionate developers just like you!

Happy hacking!

Integrate Segment to your Medusa project

Vadim Smirnov — Tue, 21 Sep 2021 16:57:53 +0000

Modern e-commerce businesses have to integrate with a wide spectrum of tools from marketing and personalization to analytics and business intelligence. Integrations to these tools quickly become hard to maintain and new integrations become overly complex to implement putting a stretch on an e-commerce organization's resources.

The CDP (Customer Data Platform) Segment solves this problem by allowing users to instantly integrate with +100 tools through a single unified API.

Medusa has an official plugin medusa-plugin-segment that instantly gives you access to all Segment integrations and comes preconfigured with powerful server-side tracking

Why Segment?

Segment is a powerful Customer Data Platform that allows users to collect, transform, send and archive their customer data.

Segment allows users to manage different tracking and marketing tools using one API and interface, making it very simple to try out and integrate with different services in your e-commerce stack.

Common integration use cases that can be implemented with Segment include:

Mailchimp
Klaviyo
Google Analytics Enhanced E-commerce tracking
Data warehousing for advanced data analytics and segmentation through services like Snowflake

Adding Segment to your Medusa store

Note: you should create a Node.js source in Segment in order to obtain the write key that will be provided in the plugin options.

Plugins in Medusa's ecosystem come as separate npm packages, that can be installed from the npm registry.

yarn add medusa-plugin-segment

After installation open medusa-config.js to configure the Segment plugin, by adding it to your project's plugin array and providing the options required by the plugin, namely the write key obtained from the Segment dashboard.

{
    resolve: `medusa-plugin-segment`,
    options: {
      write_key: SEGMENT_WRITE_KEY,
    }
}

After the plugin has been configured you will get instant access to +100 services through the Segment dashboard. This allows you to try out new services for your e-commerce stack without having to make heavy integration investments.

Default tracking

medusa-plugin-segment comes with prebuilt tracking for common flows for Orders, Returns, Swaps, and Claims. Where applicable the events follow the Segment Ecommerce Spec.

Below is a list of some of the events that are tracked by default:

Orders
- Order Completed
- Order Shipped
- Order Refunded ← Without returned products
- Order Cancelled
Returns
- Order Refunded ← With returned products
Swaps
- Swap Created
- Swap Confirmed
- Swap Shipped
Claims
- Item Claimed

The default events serve as a good foundation for e-commerce tracking, allowing you to answer questions regarding product performance, return ratios, claim statistics, and more.

In many cases you will want to track other events that are specific to your store - this is also possible through the Segment plugin, as the plugin registers the segmentService in your Medusa project.

Tracking custom events

Building from the custom functionality that can be guided by the tutorial in Medusa docs, imagine that you want to track all welcome opt-ins.

The segmentService exposes a track method that wraps Segment's Track Spec, allowing you to send events to the Segment from anywhere in your Medusa project.

For example, to add tracking of the opt-ins in the POST /welcome/:cart_id endpoint, you could add the following code:

const segmentService = req.scope.resolve("segmentService")
segmentService.track({
  event: "Welcome Opt-In Registered",
  properties: {
    cart_id,
    optin
  }
})

The above snippet would send an event to Segment for further processing. The event data could be used for:

Segmentation of a mailing list in MailChimp or Klaviyo based on whether the customer opted in for welcomes
Storage in the data warehouse for later analysis to answer questions like "Are customers who opt-in for welcomes more likely to become recurring customers?"
Integration to Google Analytics's events
etc.

What's next?

This article covers the introduction to one of many Medusa plugins and an explanation of how you can enhance your e-commerce stack, which will help you to build a successful e-commerce project.

Not sure where to start? We are happy to help and talk to you at our Discord!

Announcing Create Medusa App: One command for a full-stack headless e-commerce setup

Vadim Smirnov — Wed, 15 Sep 2021 11:28:24 +0000

With the new create-medusa-app tool you will get your Medusa development environment ready within a couple of minutes. After completion, you will have a Medusa backend, a Gatsby or Next.js storefront, and an admin dashboard up and running on your local machine.

Starting a new e-commerce project just got easier, now with one command.

Getting started with `create-medusa-app`

Use create-medusa-app with your preferred package manager:

yarn create medusa-app

npx create-medusa-app

Behind the scenes, create-medusa-app is populating your database with some initial set of mock data, which helps to interact with Medusa setup intuitively straight away.

Right after hitting one of those commands, the multistep installation process will be initiated, so the starter can be shaped right for the specific needs.

Destination folder

Enter the path to the directory that will become the root of your Medusa project:

? Where should your project be installed? › my-medusa-store

Pick the starter you prefer

? Which Medusa starter would you like to install? …
❯ medusa-starter-default
  medusa-starter-contentful
  Other

You will be presented with three options:

medusa-starter-default is the most lightweight version of a Medusa project
medusa-starter-contentful almost like the default starter, but with medusa-plugin-contentful preinstalled
Other if you have a different starter that you would wish to install from Other will give you the option of providing a URL to that starter. An additional question will be asked if you choose this option:
```
Where is the starter located? (URL or path) › https://github.com/somecoolusername/my-custom-medusa-starter
```

For the walkthrough purposes, we assume that the selected starter is medusa-starter-default and proceed to the next step.

Selecting a Storefront

After selecting your Medusa starter you will be given the option to install one of our storefront starters. At the moment we have starters for Gatsby and Next.js:

Which storefront starter would you like to install? …
❯ Gatsby Starter
  Next.js Starter
  None

You may also select None if the choice is to craft a custom storefront for your product.

create-medusa-app now has all of the info necessary for the installation to begin.

Creating new project from git: https://github.com/medusajs/medusa-starter-default.git
✔ Created starter directory layout
Installing packages...

Once the installation has been completed you will have a Medusa backend, a demo storefront, and an admin dashboard.

What's inside

Inside the root folder which was specified at the beginning of the installation process the following structure could be found:

/my-medusa-store
  /storefront // Medusa storefront starter
  /backend // Medusa starter as a backend option 
  /admin // Medusa admin panel

create-medusa-app prints out the commands that are available to you after installation. When each project is started you can visit your storefront, complete the order, and view the order in Medusa admin.

⠴ Installing packages...
✔ Packages installed
Initialising git in my-medusa-store/admin
Create initial git commit in my-medusa-store/admin

  Your project is ready 🚀. The available commands are:

    Medusa API
    cd my-medusa-store/backend
    yarn start

    Admin
    cd my-medusa-store/admin
    yarn start

    Storefront
    cd my-medusa-store/storefront
    yarn start

What's next?

To learn more about Medusa to go through our docs to get some inspiration and guidance for the next steps and further development:

If you have any follow-up questions or want to chat directly with our engineering team we are always happy to meet you at our Discord.

Setting up a Next.js storefront for your Medusa project

Vadim Smirnov — Mon, 06 Sep 2021 18:35:52 +0000

Medusa is a headless open source commerce platform giving engineers the foundation for building unique and scaleable digital commerce projects through our API-first engine.

Being headless, our starters serve as a good foundation for you to get coupled with a frontend in a matter of minutes.

This article assumes you already have the Medusa project created and ready to be linked to your Next.js starter.

Getting started

In order to get started let's open the terminal and use the following command to create an instance of your storefront:

npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront

Now we have a storefront codebase that is ready to be used with our Medusa server.

Next, we have to complete two steps to make our new shiny storefront to speak with our server: link storefront to a server and update the STORE_CORS variable.

Let's jump to these two.

Link storefront to a server

For this part, we should navigate to a client.js file which you can find in the utils folder.

We don't need to do much in here, but to make sure that our storefront is pointing to the port, where the server is running

import Medusa from "@medusajs/medusa-js";

const BACKEND_URL = process.env.GATSBY_STORE_URL || "http://localhost:9000"; // <--- That is the line we are looking for

export const createClient = () => new Medusa({ baseUrl: BACKEND_URL });

By default the Medusa server is running at port 9000, so if you didn't change that we are good to go to our next step.

Update the `STORE_CORS` variable

Here let's navigate to your Medusa server and open medusa-config.js

Let's locate the STORE_CORS variable and make sure it's the right port (which is 3000 by default for Next.js projects)

/* 
 * CORS to avoid issues when consuming Medusa from a client.
 * Should be pointing to the port where the storefront is running.
 */
const STORE_CORS = process.env.STORE_CORS || 'http://localhost:3000';

Now we have a storefront that interacts with our Medusa server and with that we have a sweet and complete e-commerce setup with a Next.js storefront.

Learn more

If you want to discover the endless possibilities of Medusa's ecosystem you can find a lot more useful resources on our docs page which can help you to build your awesome commerce project!

If you need help or have questions about how to use Medusa feel free to join our Discord to get direct access to our engineering team.

Forem: Vadim Smirnov

Storybook Starter Guide: Learn Design System Principles

What is Storybook?

Benefits of Using Storybook

Core Design System Principles in the Starter

Reusability

Composability

Consistency

Extending with Addons

Final Thoughts

How to Detect Bot Traffic using Next.js Middleware: A Quick Guide

What is Bot Detection and Why Does it Matter?

Why Should You Implement Bot Detection?

What is Middleware in Next.js?

How Next.js Middleware Works

A Simple Middleware Implementation

Extend Middleware with Bot Detection

Test the Middleware

Review of Common Bot Detection Techniques

User-Agent Header Checking

IP Address Filtering

Third-Party Bot Detection APIs

Conclusion

Create a Rich Text Editor with Astro, Preact & CKEditor 5

Why Choose Astro + Preact?

Astro:

Preact:

Why CKEditor?

Setting Up Your Astro + Preact Project

Step 1: Create a New Astro Project

Step 2: Add Preact to Your Astro Project

Step 3: Generate Your CKEditor Code

Step 4: Integrate CKEditor 5 into Your Project

1. Install CKEditor’s React Package

2. Add CKEditor Styles

3. Create an Editor Component

Step 5: Adjust Astro for Preact Compatibility

Step 6: Add the Editor to Your Page

Wrapping Up

Building a Measuring Tool with the Resize Observer API

What is the Resize Observer API?

What We’re Building

Step 1: Setting Up the Project

Step 2: The Markup

Step 3: Styling the App

Step 4: Adding Real-Time Resize Tracking

Step 5: Testing the Tool

How It Works

Conclusion

📝 🚀 Creating our first documentation from scratch using Astro and Refact AI coding assistant

Refact: Open-source AI coding assistant

Building the Starlight docs

Creating an Astro project

Adding Starlight

Configuring Starlight

Customizing your documentation

Changing the color theme

Conclusion

Next Steps

Nhost CLI: From Zero to Production

Recommended workflow with Nhost

What you’ll learn in this guide:

Setup the recommended workflow with Nhost

Create Nhost App

Create new GitHub Repository

Connect GitHub Repository to Nhost App

Install the Nhost CLI

Local changes

Apply metadata and Serverless Functions

Hasura Metadata

Serverless Function

Conclusion

Hacktober 2021 results

Hacktober 2021 community achievements

Time to give back

There is still an opportunity to be involved in Medusa development

That one thing I regret about my CSS code

What is an outline?

Why should outline stay?

Accessibility issue

What is an `outline`?

Getting started with `create-medusa-app`

Update the `STORE_CORS` variable