npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@firebits/theme-sync

v1.1.3

Published

A powerful CLI tool for syncing theme files to a remote server with real-time watching and interactive confirmation.

Downloads

7

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

sontrsontr

Keywords

Readme

@firebits/theme-sync

A powerful CLI tool for syncing theme files to a remote server with real-time watching and interactive confirmation.

Features

  • 🔄 Real-time file watching - Automatically syncs files as they change
  • 📊 Full sync analysis - Shows what files need to be uploaded, updated, or deleted
  • 🗑️ Interactive confirmation - Asks for confirmation before deleting files
  • 🚀 Fast and efficient - Uses file hashing to only sync what's changed
  • 📁 Directory support - Handles nested directories and subdirectories
  • 🔐 Secure authentication - API key-based authentication

Installation

npm install -g @firebits/theme-sync

Or use with npx:

npx @firebits/theme-sync@latest sync -p ./my-theme -t my-theme -s http://localhost:8090 -k your-api-key

Usage

Start watching with initial sync

theme-sync sync -p ./my-theme -t my-theme -s http://localhost:8090 -k your-api-key

This will:

  1. Perform an initial full sync to ensure server is up-to-date
  2. Start watching for file changes
  3. Automatically sync new, modified, or deleted files

Start watching without initial sync

theme-sync sync -p ./my-theme -t my-theme -s http://localhost:8090 -k your-api-key --no-initial-sync

Perform one-time full sync

theme-sync full-sync -p ./my-theme -t my-theme -s http://localhost:8090 -k your-api-key

This performs a full sync analysis and shows what will be changed before proceeding.

Options

sync command

  • -p, --path <path> - Local theme directory path (required)
  • -t, --theme <name> - Theme name (required)
  • -s, --server <url> - Server sync URL (required)
  • -k, --key <key> - Authentication key (required)
  • --no-initial-sync - Skip initial full sync

full-sync command

  • -p, --path <path> - Local theme directory path (required)
  • -t, --theme <name> - Theme name (required)
  • -s, --server <url> - Server sync URL (required)
  • -k, --key <key> - Authentication key (required)

Examples

# Basic usage
theme-sync sync -p ./themes/my-theme -t my-theme -s http://localhost:8090 -k your-secret-key

# Skip initial sync
theme-sync sync -p ./themes/my-theme -t my-theme -s http://localhost:8090 -k your-secret-key --no-initial-sync

# One-time sync
theme-sync full-sync -p ./themes/my-theme -t my-theme -s http://localhost:8090 -k your-secret-key

# Using npx
npx @firebits/theme-sync@latest sync -p ./themes/my-theme -t my-theme -s http://localhost:8090 -k your-secret-key

Server Requirements

The theme-sync CLI requires a compatible server with the following endpoints:

  • POST /themes/sync - For individual file operations (update/delete)
  • POST /themes/full-sync-analysis - For analyzing files without changes
  • POST /themes/full-sync - For full synchronization with optional deletion

All endpoints require API key authentication via the key parameter.

Theme Templates

Head Template (head.html)

The head.html template in your theme's templates/ directory allows you to customize the HTML tags that get injected into the <head> section of web pages. This replaces the previously hardcoded inject tags.

Location: your-theme/templates/head.html

Example:

<!-- Custom inject tags for head section -->
<!-- Developers can customize these tags for their specific needs -->
<script src="/__theme/utils.js"></script>
<script src="/__theme/w3f/w3f.js"></script>
<script src="https://unpkg.com/alpinejs" defer></script>
<script src="/__theme/inject.js"></script>
<link rel="stylesheet" href="/__theme/inject.css">

<!-- Add your custom scripts and styles here -->
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css">

Features:

  • ✅ Customizable: Add your own scripts, stylesheets, and meta tags
  • ✅ Flexible: Include external CDN resources or local theme files
  • ✅ Isolated: The head.html template is loaded separately from other templates
  • ✅ Optional: If head.html doesn't exist, no head injection occurs

Note: The head.html template is automatically excluded from the general template loading to prevent duplication.

Authentication

The CLI uses API key authentication. You need to:

  1. Configure keys on the server in config/keys.json:

    {
  "apiKeys": [
    "3604ddkkklsaEED",
    "your-secret-key-here",
    "another-key-for-different-client"
  ]
}

  2. Use the key in CLI commands:

    theme-sync sync -p ./my-theme -t my-theme -s http://localhost:8090 -k 3604ddkkklsaEED

Interactive Confirmation

When performing a full sync, the tool will show you:

📋 Full Sync Analysis:
   📁 Total files: 15
   ⬆️ New files: 2
   🔄 Outdated files: 1
   🗑️ Files to delete: 3

🗑️ Files that will be deleted from server:
   - old-file.js
   - unused.css
   - temp.html

❓ Do you want to continue with deletion? (y/n):

Type y or yes to continue, or n/no to cancel.

Requirements

  • Node.js >= 16.0.0
  • A compatible theme sync server
  • Valid API key configured on the server

License

MIT