How to Share Private Astro Components Without npm

Component Sharing and Management

In web development, there are times when you want to reuse the same UI components across multiple websites, right?

When using modern frameworks like Astro to streamline development across multiple sites, sharing a component library is very effective. However, when sharing components as npm packages, publishing private packages requires a paid plan.

This time, we'll introduce an efficient way to share and manage components using GitHub repositories and Cloudflare Pages without packaging them with npm!

What are the challenges in component sharing?

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

I see. So what's the best approach?

Solve it with a GitHub repository and custom build scripts

To address these challenges, here's how you might approach it.

1. Create a GitHub repository for components
2. Use file references for local development
3. Clone the component repository at build time in Cloudflare Pages

Component sharing and management becomes possible without using npm private packages.

Implementation looks like this

1. Create a GitHub Personal Access Token

Create a GitHub Personal Access Token to access private repositories.

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

2. Building a component library

Create a GitHub repository for your components (for example: 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 up the main project

Configure the package.json of your main project that will consume the components.

Main project package.json

{
  "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などの開発依存関係
  }
}

These 4 points are essential.

1. config section: Centralize component library information
2. setup-components script: Clone components from GitHub at build time
3. build-with-components script: Command that combines component setup and build
4. dependencies: Local file references for development

4. Set up your local development environment

Clone the component library to the same directory level as your project and use it via file references.

projects/
  ├── ui-components/         # コンポーネントライブラリ
  └── your-astro-project/     # メインプロジェクト

When you modify components during local development, changes are immediately reflected in your main project.

5. Configure Cloudflare Pages

Here's how to configure Cloudflare Pages.

1. Set environment variables:
   • Pages dashboard → your-project → Settings → Environment variables
   • Variable name: GITHUB_TOKEN
   • Value: Your generated GitHub Personal Access Token
2. Set 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 is automatically cloned and integrated during the build.

Easy component usage once configuration is complete

Once configuration is complete, using components is very straightforward.

Create src/index.ts in the component library and export your components.

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 management?

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

1. Make changes to the component library and commit them
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 components it needs.

The development flow is also secure

A secure and efficient development flow means fewer things to worry about.

1. Develop new features or make improvements in the component library (e.g., feature/new-button branch)
2. Test and verify those changes immediately in the main project in your local environment
3. Once development reaches a certain stage, create a test tag (e.g., v1.1.0-test)
4. Update componentVersion to the test tag in the main project's test environment branch and deploy to the test environment
5. Once you confirm there are no issues in the test environment, merge to the main branch of the component library
6. Creating a new version tag and updating the main project version reflects it to production (e.g., v1.1.0)

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

Since Cloudflare Pages' production environment uses the version of the tag specified by config.componentVersion, changes won't affect production unless you create a new tag and update config — so you can work with confidence!

■ Share components efficiently by combining GitHub private repositories with custom build scripts, without relying on npm private packages!

■ Seamless component sharing across your team through proper GitHub Token management and correct local development environment setup!

What do you think?

Isn't this approach ideal for small to mid-sized teams or projects that prioritize cost efficiency?

If your team or project grows in the future, you can always consider migrating to npm private packages, but for now this method enables efficient component sharing! I believe it's a solid solution.

Note: This approach is applicable to other frameworks beyond Astro (React, Vue, Svelte, etc.). Configuration details may differ, but the fundamental approach is the same! You can customize the build process similarly with hosting services other than Cloudflare Pages as well.