DEV Community: Patrick Chiu

Mitosis - Using Astro.js as the dev server to preview the component with hot-reload

Patrick Chiu — Sat, 31 Aug 2024 19:46:00 +0000

What is Mitosis
Astro.js as the dev server
Steps
- Set up Mitosis
- Set up Astro.js in /test-app
  - Framework integrations
  - Astro.js folder structure
- Update the build script
- (Bonus) .gitignore
- (Bonus) Settings of Publishing to NPM

TL;DR Here's the Mitosis Astro.js Starter repo to jump start the development. I built a GitHub Activity Widget component with a similar setup, which compiles to native React, Svelte, Vue, SolidJS and Qwik components.

What is Mitosis

In case you are new to Mitosis, Mitosis enables you to develop a consistent design system across multiple frameworks e.g. React, Svelte and Vue.

Its syntax is pretty similar to React. It allows you to write your component in JSX and transforms into native components of the various frameworks.

Astro.js as the dev server

While Mitosis is great at generating framework-native components, it doesn't come with a dev server to let you preview the component. You may ask, why do we want to preview the component in various frameworks, instead of only previewing it in one of them e.g. svelte?

Turns out there are quite a few of gotchas and open issues in using Mitosis (when this tutorial is written). Sometimes the generated code works perfectly in React and Vue but not Svelte. Sometimes the others. It would be great if

We could preview most (if not all) generated components in a single page
Even better, have hot-reload enabled

In this tutorial, we will walk through the steps to set up a hot-reload dev server with Astro.js.

Note: Astro supports a variety of popular frameworks including React, Preact, Svelte, Vue, SolidJS, AlpineJS and Lit with official integrations. While for other frameworks e.g. Angular and Qwik, you may still benefit from this tutorial and you would need to further set up the community maintained framework integrations.

Steps

1. Set up Mitosis

This step references the official Create a new project cli guide with the following modifications.

We aren't initializing test-apps for each framework. Instead, we would run one test-app with Astro.js for all frameworks.
In terms of NPM package, we aren't scoping the component under a namespace and output various packages like @my-awesome-component/library-react and @my-awesome-component/library-svelte etc. Instead, we publish all components in one package only my-awesome-component. The output components can then be imported like my-awesome-component/react and my-awesome-component/svelte etc

The folder structure should look like this by the end of this step.

.
├── src/
│   └── MyAwesomeComponent.lite.tsx
├── mitosis.config.cjs
├── package.json
└── tsconfig.json

Without further ado, let's initiate an empty project.

mkdir my-awesome-component
cd ./my-awesome-component
npm init -y

Install the relevant packages

npm i @builder.io/eslint-plugin-mitosis @builder.io/mitosis @builder.io/mitosis-cli
npm i watch --save-dev

Setup mitosis.config.cjs. In the targets field, place all downstream frameworks to compile.

/**
 * @type {import('@builder.io/mitosis').MitosisConfig}
 */
module.exports = {
  files: 'src/**',
  targets: ['react', 'svelte', 'solid', 'vue'],
  dest: 'output',
  commonOptions: {
    typescript: true,
  },
  options: {
    react: {
      stylesType: 'style-tag',
    },
    svelte: {},
    qwik: {},
  },
};

Setup tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "strict": true,
    "jsx": "preserve",
    "noImplicitAny": false,
    "moduleResolution": "node",
    "jsxImportSource": "@builder.io/mitosis"
  },
  "include": ["src"]
}

Initialize src/MyAwesomeComponent.lite.tsx

import { useState } from "@builder.io/mitosis";

export default function MyComponent(props) {
  const [name, setName] = useState("Steve");

  return (
    <div>
      <input
        css={{
          color: "red",
        }}
        value={name}
        onChange={(event) => setName(event.target.value)}
      />
      Hello! I can run natively in React, Vue, Svelte, Qwik, and many more frameworks!
    </div>
  );
}

2. Set up Astro.js in `/test-app`

The folder structure should look like this by the end of this step. We will focus on test-app

.
├── src/
│   └── MyAwesomeComponent.lite.tsx
├── test-app/
│   └── astro.config.mjs
├── mitosis.config.js
├── package.json
└── tsconfig.json

Create astro project with the following config

npm create astro@latest

# Where should we create your new project?
./test-app

# How would you like to start your new project?
Empty

# Do you plan to write TypeScript?
Yes

# How strict should TypeScript be?
Strict

# Install dependencies?
Yes

# Initialize a new git repository?
No

Cd into the directory

cd test-app

2.1. Framework integrations

Follow the official integration guide to add React.js, Vue, Svelte and Solid.js. (You can add more if you need)

npx astro add react
npx astro add vue
npx astro add svelte
npx astro add solid

Since both React.js and Solid.s uses JSX, we need to let Astro.js where to find both correspondingly. Update astro.config.mjs with the following settings.

import { defineConfig } from 'astro/config';

import react from '@astrojs/react';
import solid from '@astrojs/solid-js';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';

export default defineConfig({
  integrations: [
    react({
      include: ['**/react/**'],
    }),
    solid({
      include: ['**/solid/**'],
    }),
    svelte(),
    vue(),
  ],
});

2.2. Astro.js folder structure

Let's structure our Astro.js test-app like the following and import all components to index.astro.

.
├── test-app/
│   ├── src/
│   │   ├── components/
│   │   │   ├── react/
│   │   │   │   └── ReactApp.tsx
│   │   │   ├── solid/
│   │   │   │   └── SolidApp.tsx
│   │   │   ├── SvelteApp.svelte
│   │   │   └── VueApp.vue
│   │   └── pages/
│   │       └── index.astro
│   └── astro.config.mjs

See the GitHub repo for content in ReactApp.tsx, SvelteApp.svelte, VueApp.vue and SolidApp.tsx.

For index.astro, replace with the following. This wires up various framework components into a single Astro.js page.

---
import ReactApp from '../components/react/ReactApp.jsx'
import SvelteApp from '../components/SvelteApp.svelte'
import VueApp from '../components/VueApp.vue'
import SolidApp from '../components/solid/SolidApp.jsx'
---

<html lang="en">
  <head>
    <meta charset="utf8" />
    <title>Test App</title>
  </head>

  <body>
    <div class="w-50">
      <div class="title">
        <span>React</span>
      </div>
      <ReactApp client:only="react" />
    </div>
    <div class="w-50">
      <div class="title">
        <span>Svelte</span>
      </div>
      <SvelteApp client:load />
    </div>
    <div class="w-50">
      <div class="title">
        <span>Vue</span>
      </div>
      <VueApp client:only="vue" />
    </div>
    <div class="w-50">
      <div class="title">
        <span>Solid</span>
      </div>
      <SolidApp client:only="solid-js" />
    </div>
  </body>
</html>

<style>
  body {
    background-color: aliceblue;
  }

  .w-50 {
    display: inline-block;
    width: calc(48% - 12px * 2 - 8px * 2);
    margin: 8px;
    padding: 12px;
    border-radius: 8px;
    box-shadow: 0px 1px 4px rgba(0, 0, 0, 0.1);
    background-color: white;
  }

  .title {
    display: flex;
    align-items: center;
    gap: 6px;
    margin-bottom: 8px;
  }
</style>

3. Update the build script

Now let's wire up Mitosis and Astro.js! Update the root package.json with the following.

npm run build: Mitosis generates downstream components to ./output and we copy it to ./test-app/src
npm run start: we watch changes in ./src and npm run build when there are changes

{
  // ...
  "scripts": {
    "start": "watch \"npm run build\" ./src",
    "build": "mitosis build --c mitosis.config.cjs && cp -R ./output ./test-app/src",
    "lint": "eslint"
  },
  // ...
}

4. (Bonus) .gitignore

Mitosis build script would compile the downstream component to ./output. Let's ignore it together with ./node_modules and Astro.js' generated types

# dependencies
node_modules/

# Mitosis
output/

# Astro.js
.astro/

5. (Bonus) Settings of Publishing to NPM

Now you have built an awesome Mitosis component. Let's update package.json so that developers of various frameworks can use your component!

(Don't forget to change the actual package name from my-awesome-component to something else!)

{
  "name": "my-awesome-component",
  // ...
  "main": "./output/react/src/MyAwesomeComponent.tsx",
  "exports": {
    "./react": "./output/react/src/MyAwesomeComponent.tsx",
    "./svelte": "./output/svelte/src/MyAwesomeComponent.svelte",
    "./vue": "./output/vue/src/MyAwesomeComponent.vue",
    "./solid": "./output/solid/src/MyAwesomeComponent.tsx"
  },
  "files": [
    "output/**/*"
  ]
}

The above settings do 2 things

You only publish the generated downstream components in the ./output directory to NPM
Your component can be imported with...

// React
import MyAwesomeComponent from 'my-awesome-component/react';

// Vue
import MyAwesomeComponent from 'my-awesome-component/vue';

// Svelte
import MyAwesomeComponent from 'my-awesome-component/svelte';

// Solid
import MyAwesomeComponent from 'my-awesome-component/solid';

Hope you enjoy the journey of setting up Mitosis with Astro.js which enables you to preview all the generated components at a glance! Lastly, do you need a quick walkthrough on creating a Mitosis component? Here's how to develop the Github Activity Calendar with Mitosis 😉

Turn your Cloudflare Workers and KV into a fast serverless cache store with HTTP endpoints

Patrick Chiu — Sat, 26 Aug 2023 01:52:23 +0000

tl;dr Here's the Git repo you can instantly deploy to your Cloudflare Workers and KV with read, write, delete and list functionalities

In this tutorial, we will create a simple Cloudflare Workers app that read and write to the KV with the value we provide. Before that, we will discuss how we can leverage this idea and make it a feasible option as a fast HTTP-based KV store for any external application to use.

Table of Content

How can it be useful?
Designing the KV endpoints
Set up Workers and KV
Implementing the Write functionality
Implementing the Read functionality
Deploy and Test it
Epilogue and Cache Cloud which does all the KV stuff for you!

How can it be useful?

Workers KV is the built-in edge storage offering of the Cloudflare Workers ecosystem. It is exceptionally fast and always nearby your Workers app (after the initial reads). And guess what? Workers is also edgy and nearby your main application with a very low latency.

How fast is it? Below is the benchmarks summary of making HTTP requests to a Cloudflare Workers app which connects to the KV. And here's the link of the detailed results.

Note: we usually expect read and list to be as fast as possible, while we can tolerate write and delete to be slower.

In addition, Workers and KV are serverless. Cloudflare manages the infrastructure and servers for us. We don't need to worry about the auto-scaling and it supports 0ms cold starts too.

Designing the KV endpoints

KV is only callable from Workers, and this is why we need to expose an HTTP interface via Workers, so that it can be used externally.

Here's what it looks like to "Get a cached value by key" from your main app.

// You can define your own `cacheKey`, save and get values from it
// e.g. user%3A1%3A <= encodeURIComponent('user:1:')
const cacheKey = 'latest-blog-posts';
const response = await fetch(`${YOUR_CLOUDFLARE_WORKERS_HOST}/kv/values/${cacheKey}`);

const { success, result: latestBlogPosts } = await response.json();
if (!success || !latestBlogPosts) {
  // Cache not found :(
  // Fetch and cache it here!
}

// Cache found, return it instantly!
return res.json(latestBlogPosts);

The essential functionality of a KV store is read and write. Let's design 2 endpoints for each of them.

Note: let's ignore the error handling and focus on the core functionality for now.

1. Read operation

GET /kv/values/{{key}}

Path Parameter

Field	Type	Description
key	string	The cache key to get value from

Response Body

Field	Type	Description
result	any or `null`	If there is value in the cache key, well, it will be the value If there isn't, it will be `null`

2. Write operation

PUT /kv/values/{{key}}

Path Parameter

Field	Type	Description
key	string	The cache key to upsert value

Request Body

Field	Type	Description
value	Any	The value to be writen to the cache key `{{key}}`
expirationTtl	integer	seconds from now that the cache will expire

Response Body

Field	Type	Description
success	boolean	Whether the operation is successful

Set up Workers and KV

Assume you have created a Cloudflare account already. If not, visit this link to create one before proceeding!

1. Create a new Worker project

npm create cloudflare@latest

This will prompt you to install the create-cloudflare package, and lead you through setup.

For this guide, set up a basic Worker:

Name your new Worker name my-serverless-cache-store.
Select "Hello World" script as the type of application you want to create.
Select Yes for the question Do you want to deploy your application? because Cloudflare requires us to deploy a Workers before we can configure a KV afterwards

Since its the first time we deploy, Cloudflare requires us to login via the terminal. Select "Allow" Wrangler to make changes to our account.

After that, Wrangler should have deploy a Workers app with a public link.

In your project directory, C3 (create-cloudflare-cli) has generated the following:

wrangler.toml: Your Wrangler configuration file.
worker.js (in /src): A minimal 'Hello World!' Worker written in ES module syntax.
package.json: A minimal Node dependencies configuration file.

2. Install `hono` and setup the KV endpoints

As you see, Cloudflare Worker's default way of handling HTTP request is to define the fetch method, which might feel foreign to developers that are familiar to Express.js or Koa.js.

Let's cd into our worker my-serverless-cache-store and install Hono.js which is a web framework that works very well with Cloudflare Workers.

cd ./my-serverless-cache-store
npm install hono --save

After that, let's update worker.js (in /src) as followed to return a dummy response to our read and write KV endpoints.

import { Hono } from 'hono';
const app = new Hono();

app.get('/kv/values/:cacheKey', (c) => {
  const cacheKey = c.req.param('cacheKey');
  return c.json({ cacheKey });
});

app.put('/kv/values/:cacheKey', async (c) => {
  const cacheKey = c.req.param('cacheKey');
  const body = await c.req.json();
  return c.json({ cacheKey, body });
});

export default app;

For the Read endpoint, we return whatever is passed as the cacheKey.

For the Write endpoint, we return the cacheKey as well as the request body. Note: remember to add the async keyword, since the function to parse request body c.req.json() needs to be awaited.

You can spin up the Workers app locally by npx wrangler dev --remote=true. remote=true here means that we want to use the actual KV in Cloudflare, but not an in-memory one.

Let's try out the dummy endpoints with Postman!

Looks good!

3. Configure KV

Next, configure a KV in Cloudflare's dashboard by

Clicking "KV"
Clicking "Create a namespace"
Naming your KV namespace (The name doesn't matter. All it matters is the KV ID in step 4)
"Add"

4. Bind KV to the Workers app

Next, let's bind KV to the Workers app by specifying the KV ID in the wrangler.toml. You can find the ID via Cloudflare dashboard here.

Update the [[kv_namespaces]] of your wrangler.toml as followed with the xxxxxx replaced by the real KV ID.

[[kv_namespaces]]
binding = "KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
preview_id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Now in Hono route handler, you can access the KV by c.env.KV!

Yes, in actual development, we should create another KV for the preview_id. For simplicity here, use the same id for now.

Implementing the Write functionality

app.put('/kv/values/:cacheKey', async (c) => {
  const cacheKey = c.req.param('cacheKey');
  const { value, expirationTtl = 3600 } = await c.req.json();

  // If value is a JSON, stringify it
  // KV put() accepts only strings, ArrayBuffers, ArrayBufferViews, and ReadableStreams as values.
  let cacheValue = value;
  try {
    cacheValue = JSON.stringify(value);
  } catch (e) {}

  await c.env.KV.put(cacheKey, cacheValue, { expirationTtl });

  return c.json({ success: true });
});

The updates we made:

Destructuring value and expirationTtl from the request body
Assign a default value 3600 to expirationTtl - by default the cache will expire after 1 hour (60s * 60m)
Try to stringify the value if it's a JSON. If not, keep it as-is
Use c.env.KV.put to write the cacheValue to the specified cacheKey and expirationTtl

Implementing the Read functionality

app.get('/kv/values/:cacheKey', async (c) => {
  const cacheKey = c.req.param('cacheKey');
  const result = await c.env.KV.get(cacheKey);

  try {
    return c.json({ result: JSON.parse(result) });
  } catch (e) {
    return c.json({ result });
  }
});

The updates we made:

Update the handler to ba async
Use c.env.KV.get to read the cache value
Try to parse the result and return a JSON-ize response. If not, return the result as-is

Deploy and Test it

Let's deploy our read write endpoints to Cloudflare and test it!

npx wrangler deploy

Write a cache

E.g. caching your latest blog posts

Read the cache value

The speed is quite fast with a 33ms.

Note: It is probably much slower the first time you read the value, since Cloudflare didn't cache the KV to the edge location, until your initial read. After that, it will be ultrafast!

You can also view the cached value in the Cloudflare dashboard

Epilogue and Cache Cloud

We've learnt how to use KV in Workers and gone through the steps to utilize Workers and KV to create a serverless KV store.

If you want a full version of the KV store, I've built Cache Cloud which you can instantly deploy to your Cloudflare Workers with read, write, delete, list and bulk read/write/delete functionalities. (Shameless plug hehe)

Adding a GitHub Contribution Calendar to your Svelte App

Patrick Chiu — Sun, 16 Apr 2023 03:57:14 +0000

Showcasing your GitHub activities in the personal site is a great way to demonstrate one's enthusiasm and determination to your works. This short article aims at introducing activity-calendar-widget that can be embedded in your Svelte App! In fact, activity-calendar-widget also provides native components in framework e.g. React, Vue, Solid and Qwik as well, but we will focus on the usage in a Svelte App here.

Installation

npm i activity-calendar-widget

Basic Example

<script>
  import ActivityCalendarWidget from 'activity-calendar-widget/svelte'
</script>

<div>
  <ActivityCalendarWidget daysToRender={150} />
</div>

<style>
  img { width: 82px }
</style>

Since we are working on a Svelte codebase, we import ActivityCalendarWidget from 'activity-calendar-widget/svelte' (notice the subdirectory /svelte at the end). After that, we can embed the <ActivityCalendarWidget /> into our Svelte App. And duh! We have an (empty) GitHub Contribution Calendar!

In the basic example, we also pass daysToRender={150} to the component. If we remove the props, by default it will at least render 365 days and try to fill out all the empty day box in the leftmost (oldest) column.

It's a shame to see an empty GitHub Contribution Calendar! Let's walkthrough 2 options in our hands - getting the public activity data using the official GitHub events API, or getting the exact data in your profile's contributions with GitHub contributions API created by @grubersjoe. It is a handy API which scrapes the data from your profile.

Usage with the official GitHub events API

<script>
  import ActivityCalendarWidget from 'activity-calendar-widget/svelte'

  let data = []

  const loadGithubActivity = async () => {
    // 1. Call Github events API
    const githubId = 'patrick-kw-chiu';
    const githubApi = `https://api.github.com/users/${githubId}/events`;
    const response = await fetch(githubApi);
    const payload = await response.json();

    // 2. Report error if there's
    if (payload?.message) {
      return;
    }

    // 3. Construct the data array which expects obj with 2 keys
    // date: 'yyyy-MM-dd'
    // activities: array of anything
    let eventObj = {};
    payload.forEach((event) => {
      const date = event.created_at.slice(0, 10);
      if (!eventObj[date]) {
        eventObj[date] = [event];
      } else {
        eventObj[date] = [...eventObj[date], event];
      }
    });
    const newData = Object.entries(eventObj).map((entry) => {
      return {
        date: entry[0],
        activities: entry[1],
      };
    });
    data = newData
  }
  loadGithubActivity()
</script>

<div>
  <ActivityCalendarWidget
    daysToRender={150}
    data={data}
    levelColorMode={'dark'}
  />
</div>

<style>
  img { width: 82px }
</style>

To do so, first we GET the activities data from https://api.github.com/users/${githubId}/events where githubId is your GitHub ID.

Next, we construct a data array with 2 keys - date and activities, while date is having the yyyy-MM-dd format and activities is an array of anything. Note that the length of the activities array will be the count. Also, we can pass an optional clickHandler to retrieve the detail of the activities. We will demo it in the last section.

Lastly, we pass the data array to the widget like <ActivityCalendarWidget data={data} />. We should see something like:

Usage with the GitHub contributions API from @grubersjoe

<script>
  import ActivityCalendarWidget from 'activity-calendar-widget/svelte'

  let data = []

  const loadGithubActivity = async () => {
    // 1. Call Github events API
    const githubId = 'patrick-kw-chiu';
    const githubApi = `https://github-contributions-api.jogruber.de/v4/${githubId}`;
    const response = await fetch(githubApi);
    const payload = await response.json();

    // 2. Report error if there's
    if (!payload?.contributions) {
      return;
    }

    // 3. Construct the data array which expects obj with 2 keys
    // date: 'yyyy-MM-dd'
    // activities: array of anything
    const newData = payload.contributions.map((contribution) => {
      return {
        date: contribution.date,
        activities: new Array(contribution.count).fill(0),
      }
    });
    data = newData
  }
  loadGithubActivity()
</script>

<div>
  <ActivityCalendarWidget
    daysToRender={150}
    data={data}
    levelColorMode={'dark'}
  />
</div>

<style>
  img { width: 82px }
</style>

It is basically very similar to the official GitHub events API. The difference are that

GitHub contributions API reflects the exact contributions view from your profile, which is good
GitHub contributions API returns the contributions / activities like below, which might not include the full detail of the activity (if you need it)

{
  "contributions": [
    {
      "date": "2020-01-01",
      "count": 0,
      "level": 0
    },
    ...
  ]
}

Customize the activities calendar with other options and try out `clickHandler`

<script>
  const clickHandler = (dt) => console.log(dt)
</script>

<ActivityCalendarWidget
  daysToRender={150}
  data={data}
  levelColorMode={'dark'}
  levelColors={[
    '#021f1f', '#055e5e', '#068f8f', '#06d1d1', '#07ffff'
  ]}
  weekdayLabel={{
    1: '月曜日',
    3: '水曜日',
    5: '金曜日'
  }}
  clickHandler={clickHandler}
/>

We can customize the activities calendar widget by passing various props. In the sample above, we pass the levelColors array to change it to a teal-ish color and customize the weekdayLabel to some Japanese characters. Visit the API doc for all the supported options!

Lastly, if we click the teal-ish date box, we should see the log as below, since we pass a clickHandler to the widget. It includes the activities detail of the clicked date, as well as other info e.g. year, month and day.

Behind the scene

Activity Calendar Widget is built with Mitosis (with a little modifications), which aims to "Write components once, compile to every framework". That's why there are also native React components, Vue, Solid and Qwik as well. Interested to learn more? Here is a walkthrough of building a "simplied" Activity Calendar Widget with Mitosis.js.

Credits: The API of Activity Calendar Widget is highly influenced by React Activity Calendar. React Activity Calendar is a great component library, which provides more granular options in certain areas.

Thanks for reading! Want to Connect?

Visit me at LinkedIn | GitHub | Twitter

DEV Community: Patrick Chiu

Mitosis - Using Astro.js as the dev server to preview the component with hot-reload

What is Mitosis

Astro.js as the dev server

Steps

1. Set up Mitosis

2. Set up Astro.js in /test-app

2.1. Framework integrations

2.2. Astro.js folder structure

3. Update the build script

4. (Bonus) .gitignore

5. (Bonus) Settings of Publishing to NPM

Turn your Cloudflare Workers and KV into a fast serverless cache store with HTTP endpoints

Table of Content

How can it be useful?

Designing the KV endpoints

1. Read operation

Path Parameter

Response Body

2. Write operation

Path Parameter

Request Body

Response Body

Set up Workers and KV

1. Create a new Worker project

2. Install hono and setup the KV endpoints

3. Configure KV

4. Bind KV to the Workers app

Implementing the Write functionality

Implementing the Read functionality

Deploy and Test it

Write a cache

Read the cache value

Epilogue and Cache Cloud

Adding a GitHub Contribution Calendar to your Svelte App

Installation

Basic Example

Usage with the official GitHub events API

Usage with the GitHub contributions API from @grubersjoe

Customize the activities calendar with other options and try out clickHandler

Behind the scene

2. Set up Astro.js in `/test-app`

2. Install `hono` and setup the KV endpoints

Customize the activities calendar with other options and try out `clickHandler`