Topics

Component sharing management

In web development, there are rare cases where you want to reuse the same UI components across multiple websites, right?

If you want to streamline the development of multiple sites using a modern framework like Astro, sharing component libraries is very effective. However, if you share components as npm packages,Paid plans are required for publishing private packagesYou will need it.

This time, we will introduce a way to efficiently share and manage components using a GitHub repository and Cloudflare Pages without packaging them with npm!

What are the challenges of component sharing?

• I want to use the same UI components across multiple Astro sites!
• I want to host with Cloudflare Pages!
• I want to manage components in a private repository on GitHub!
• I want to package my component as an npm package, but I don't want to make it public!

It looks like this. So what should you do?

Solved with a GitHub repository and custom build scripts

To solve these problems, I think it would be a good idea to try something like this:

1. Create a GitHub repository for your component
2. Use file references for local development
3. Cloudflare Pages environment clones component repository at build time

This allows you to share and manage components without using private npm packages.

The implementation looks like this

1. Create a GitHub Personal Access Token

Create a GitHub Personal Access Token to access your private repositories.

1. Log in to GitHub
2. Click the profile icon in the top right corner → Settings
3. From the left sidebar, select "Developer settings" → "Personal access tokens" → "Tokens (classic)"
4. Click "Generate new token" → "Generate new token (classic)"
5. Give the token the following permissions:
   • repo- Full access to private repositories
6. Generate a token and store it somewhere safe (it will only be displayed once)

2. Building a Component Library

Create a GitHub repository for your component (e.g.github.com/your-username/ui-components）。

Component library package.json

{
  "name": "@your-org/components",
  "private": true,
  "type": "module",
  "main": "src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  },
  "files": [
    "src"
  ],
  "peerDependencies": {
    "astro": "^5.7.12"
  }
}

3. Set the main project

Configure the package.json of your main project to use the component.

package.json in the main project

{
  "name": "your-astro-project",
  "type": "module",
  "private": true,
  "config": {
    "componentVersion": "v1.0.0",
    "orgName": "your-username",
    "repoName": "ui-components",
    "namespace": "your-org",
    "packageName": "components"
  },
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "setup-components": "set -e; ORG_NAME=\\\\"$npm_package_config_orgName\\\\"; REPO_NAME=\\\\"$npm_package_config_repoName\\\\"; NAMESPACE=\\\\"$npm_package_config_namespace\\\\"; PACKAGE_NAME=\\\\"$npm_package_config_packageName\\\\"; VERSION=\\\\"$npm_package_config_componentVersion\\\\"; mkdir -p temp; git clone -b $VERSION <https://$GITHUB_TOKEN@github.com/$ORG_NAME/$REPO_NAME.git> temp/$REPO_NAME; mkdir -p node_modules/@$NAMESPACE; ln -sf $(pwd)/temp/$REPO_NAME node_modules/@$NAMESPACE/$PACKAGE_NAME",
    "build-with-components": "npm run setup-components && npm run build"
  },
  "dependencies": {
    "@your-org/components": "file:../ui-components"
  },
  "devDependencies": {
    // Astroなどの開発依存関係
  }
}

The following four points are key.

1. config section:Centralized management of component library information
2. setup-components script:Clone components from GitHub at build time
3. build-with-components script:A command that combines the setup and build of a component
4. dependencies：File references for local development

4. Set up your local development environment

Clone the component library into the same directory as your project and use it as a file reference.

projects/
├── ui-components/ # Component library
└── your-astro-project/ # Main project

Any changes you make to your components while developing locally are immediately reflected in your main project.

5. Setting up Cloudflare Pages

Here's how to set it up on Cloudflare Pages.

1. Setting environment variables:
   • Pages dashboard → your-project → Settings → Environment variables
   • Variable names:GITHUB_TOKEN
   • Value: The GitHub Personal Access Token you created
2. Configuring the build command:
   • Pages Dashboard → your-project → Settings → Build & deployments
   • Build command: npm run build-with-components
   • Build output directory: dist(default)

The specified version of the component library will be automatically cloned and included at build time.

Once setup is complete, components are easy to use

Once configured, using the component is very easy.

In the component librarysrc/index.tsand export the component.

export { default as Button } from './components/base/Button.astro';
export { default as Heading } from './components/base/Heading.astro';
// 他のコンポーネントもここでエクスポート

Import the components you want to use in your main project.

---
import { Button, Heading } from '@your-org/components';
---

<div>
  <Heading>Hello World</Heading>
  <Button>Click me</Button>
</div>

What about version control?

When you want to release a new version of your component library,

1. Make changes to the component library and commit
2. Create a new tag (e.g.v1.1.0）
3. Update package.json in the main project

   "config": {
     "componentVersion": "v1.1.0",
     // 他の設定...
   }
   
   

Each project can use the version of a component that it needs.

Development flow is also safe

It's great that the development flow is safe and efficient, with fewer things to worry about.

1. Develop new features or make improvements to the component library (e.g.feature/new-buttonbranch)
2. You can instantly test and confirm the changes in your local environment in the main project.
3. Once development has progressed to a certain stage, create a test tag (e.g.v1.1.0-test）
4. In the test branch of the main projectcomponentVersionUpdate to the test tag and deploy to the test environment
5. Once you have confirmed that there are no problems in the test environment, merge it into the main branch of the component library.
6. This is pushed to production by creating a new version tag and updating the version in the main project (e.g.v1.1.0）

The key point is that you can test component changes without affecting the production environment!

Cloudflare Pages production environmentconfig.componentVersionSince it uses the version of the tag specified inconfigYou can rest assured that the changes will not affect your production environment unless you update the

■ Combine GitHub private repositories and custom build scripts without using private npm packages!

■ Proper management of GitHub Tokens and correct configuration of local development environments allows for seamless component sharing across the entire team!

What do you think?

Perfect for small to medium-sized teams and cost-effective projects.

In the future, as our team and project grow, we may consider migrating to npm private packages, but for now, we think this method provides a sufficiently efficient way to share components!

supplement: This can also be applied to frameworks other than Astro (React, Vue, Svelte, etc.). The configuration details may differ, but the basic approach is the same! You can customize your build process in a similar way even with hosting services other than Cloudflare Pages.