Tandem Paperclip Dev Tools

1.0.3 verified Fri May 01 auth: no javascript

Development tools for Tandem's Paperclip component system. Version 1.0.3. This package is intended to scan project directories for .pc (Paperclip) files, filter components with <meta name="preview" />, generate preview hashes based on <meta name="hash" value="[generated by tandem]">, generate .d.ts files, and keep Paperclip files organized. It also includes a vanilla transpiler for Paperclip templates, with support for hooks like import, style, if conditions, event registering, and repeat. The package appears to be in early development with many TODOs remaining. No release cadence documented. Key differentiator: integrates with Tandem's visual editor ecosystem and the Paperclip component format.

Common errors

error Error: Cannot find module 'tandem-paperclip-dev-tools' ↓

cause Package is not installed or misspelled in npm install command.

fix

Run npm install tandem-paperclip-dev-tools or check package.json for correct name.

error TypeError: transpiler.transpile is not a function ↓

cause Transpiler class may not have the expected method or was imported incorrectly.

fix

Check the import: import { Transpiler } from 'tandem-paperclip-dev-tools'. Try transpiler['transpile'] or inspect the instance.

error Module '"tandem-paperclip-dev-tools"' has no exported member 'scanPaperclipFiles'. ↓

cause TypeScript cannot find the named export because package does not ship types.

fix

Use a // @ts-ignore comment before import or add a declaration module in a .d.ts file: declare module 'tandem-paperclip-dev-tools';

error Error: Cannot find module 'tandem-paperclip' ↓

cause Required peer dependency tandem-paperclip is not installed.

fix

Install tandem-paperclip: npm install tandem-paperclip.

Warnings

breaking API is unstable and likely to change; many features are not yet implemented (see README TODOs). ↓

fix Pin to a specific version and test upgrades manually; treat as pre-1.0.

gotcha Package currently does not export types properly; TypeScript users may need to declare module or use @ts-ignore. ↓

fix Wrap imports in a // @ts-ignore comment or create a .d.ts declaration file manually.

deprecated The vanilla transpiler's event registration API is not yet implemented; attempting to use it will throw. ↓

fix Avoid using event registrator features until a stable release; use manual DOM event handlers instead.

gotcha scanPaperclipFiles does not ignore node_modules by default; scanning a large project may cause performance issues. ↓

fix Pass a specific directory or use glob patterns to exclude node_modules.

deprecated The <import /> and <style /> tags in Paperclip templates are not yet supported by the transpiler. ↓

fix Wait for future updates; avoid using these tags in templates if you need transpilation.

Install

npm install tandem-paperclip-dev-tools

yarn add tandem-paperclip-dev-tools

pnpm add tandem-paperclip-dev-tools

Imports

Transpiler

wrong

const Transpiler = require('tandem-paperclip-dev-tools').Transpiler

correct

import { Transpiler } from 'tandem-paperclip-dev-tools'

ESM imports are preferred; CommonJS require still works but avoid destructuring from require

scanPaperclipFiles

wrong

const { scanPaperclipFiles } = require('tandem-paperclip-dev-tools')

correct

import { scanPaperclipFiles } from 'tandem-paperclip-dev-tools'

Ensure named export matches exactly, documentation may be incomplete

generatePreviewHash

wrong

import generatePreviewHash from 'tandem-paperclip-dev-tools'

correct

import { generatePreviewHash } from 'tandem-paperclip-dev-tools'

Default export is not available; this is a named export

Quickstart

Scans for Paperclip files in a directory and transpiles them using the built-in Transpiler.

import { Transpiler, scanPaperclipFiles } from 'tandem-paperclip-dev-tools';

const files = scanPaperclipFiles('./src');
const transpiler = new Transpiler();
for (const file of files) {
  const result = transpiler.transpile(file.content);
  console.log(result);
}