@epubknowledge/common

Shared runtime helpers for the Epub Knowledge package ecosystem.

Install From NPM

After public testing is complete and this package is published to the public NPM registry, install it directly from NPM with no extra registry configuration or auth token:

pnpm:

pnpm add @epubknowledge/common

yarn:

yarn add @epubknowledge/common

npm:

npm install @epubknowledge/common

Requires Node.js >= 22.0.0.

Install From GitHub Packages

This package is published to the GitHub Package Registry, so consuming repos must be configured to read the @epubknowledge scope from https://npm.pkg.github.com.

1. Configure the registry

Add this to the consuming repo's .npmrc:

@epubknowledge:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Commit the file, but never commit the token itself.

If the consuming repo uses Yarn Berry (v2+), add the equivalent to .yarnrc.yml:

npmScopes:
  epubknowledge:
    npmRegistryServer: 'https://npm.pkg.github.com'
    npmAuthToken: '${GITHUB_TOKEN}'

2. Provide a token

The token needs read:packages. If the org uses SSO, the token must also be authorized for epubknowledge.

Local development:

export GITHUB_TOKEN=ghp_your_token_here

GitHub Actions:

permissions:
  contents: read
  packages: read

steps:
  - run: npm install
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3. Install the package

pnpm:

pnpm add @epubknowledge/common

yarn:

yarn add @epubknowledge/common

npm:

npm install @epubknowledge/common

Importing

Import from the documented subpath exports only. There is currently no root barrel export, so prefer paths like @epubknowledge/common/dir.

Public subpath exports

• @epubknowledge/common/constants (internal) — exported for use by other @epubknowledge packages only; may change without notice between minor versions; external consumers should not depend on it
• @epubknowledge/common/dir
• @epubknowledge/common/epub
• @epubknowledge/common/file
• @epubknowledge/common/misc
• @epubknowledge/common/objectSetup
• @epubknowledge/common/paths
• @epubknowledge/common/resetMemory
• @epubknowledge/common/tmp
• @epubknowledge/common/types
• @epubknowledge/common/zip

JavaScript example

import { isDir, verifyBookDir } from '@epubknowledge/common/dir'
import { fileExists } from '@epubknowledge/common/file'

if (isDir('./book') && fileExists('./book/chapter.xhtml')) {
  console.log(verifyBookDir('./book'))
}

TypeScript example

No separate @types package is needed. This package ships its own declaration files, so TypeScript consumers can use the same import paths as JavaScript consumers and import type for type-only imports.

import { epubMove } from '@epubknowledge/common/epub'
import type { EpubObj, EpubMoveResult } from '@epubknowledge/common/types'

export async function moveBook(book: EpubObj): Promise<EpubMoveResult> {
  return epubMove(book)
}

TypeScript consumers should use modern package resolution (moduleResolution: 'bundler', 'node16', or 'nodenext') so package subpath exports resolve cleanly.

Import Readiness Plan

The repo plan for publishing and verifying consumer installs lives in docs/importing.md.

Development

npm test
npm run test:coverage
npm run build

Environment

Create a .env file in the project root to configure the tmp directory:

TMP_DIR=/path/to/your/tmp

If TMP_DIR is missing, the tmp module creates a system tmp directory for the current run. It only writes that path back to .env when create(..., true) is used and the .env file already exists.