migrate

KO | EN

gitlite — search

#javascript #php #ruby #python #java #erlang #c-sharp #jquery #logic-programming #android #game-engine #module

★ 70 Open GitHub ↗

Command-line tools for migrating posts and members from platforms like Substack, WordPress, and Medium to Ghost

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Migrate

A collection of tools for migrating to Ghost.

Each tool has its own detailed documentation:

- [Ghost](https://github.com/TryGhost/migrate/tree/main/packages/mg-ghost-api)
- [beehiiv](https://github.com/TryGhost/migrate/tree/main/packages/mg-beehiiv)
- [beehiiv API](https://github.com/TryGhost/migrate/tree/main/packages/mg-beehiiv-api)
- [beehiiv API Members](https://github.com/TryGhost/migrate/tree/main/packages/mg-beehiiv-api-members)
- [beehiiv Members](https://github.com/TryGhost/migrate/tree/main/packages/mg-beehiiv-members)
- [Blogger](https://github.com/TryGhost/migrate/tree/main/packages/mg-blogger)
- [Buttondown](https://github.com/TryGhost/migrate/tree/main/packages/mg-buttondown)
- [Chorus](https://github.com/TryGhost/migrate/tree/main/packages/mg-chorus)
- [Curated](https://github.com/TryGhost/migrate/tree/main/packages/mg-curated-export)
- [Curated members](https://github.com/TryGhost/migrate/tree/main/packages/mg-curated-members-csv)
- [Jekyll](https://github.com/TryGhost/migrate/tree/main/packages/mg-jekyll-export)
- [Letterdrop](https://github.com/TryGhost/migrate/tree/main/packages/mg-letterdrop)
- [Libsyn](https://github.com/TryGhost/migrate/tree/main/packages/mg-libsyn)
- [Mailchimp Members](https://github.com/TryGhost/migrate/tree/main/packages/mg-mailchimp-members)
- [Medium Content](https://github.com/TryGhost/migrate/tree/main/packages/mg-medium-export)
- [Medium Members](https://github.com/TryGhost/migrate/tree/main/packages/mg-medium-members)
- [Squarespace](https://github.com/TryGhost/migrate/tree/main/packages/mg-squarespace-xml)
- [Stripe](https://github.com/TryGhost/migrate/tree/main/packages/mg-stripe)
- [Substack](https://github.com/TryGhost/migrate/tree/main/packages/mg-substack)
- [Substack members](https://github.com/TryGhost/migrate/tree/main/packages/mg-substack-members-csv)
- [Tiny News](https://github.com/TryGhost/migrate/tree/main/packages/mg-tinynews)
- [Tiny News Members](https://github.com/TryGhost/migrate/tree/main/packages/mg-tinynews-members)
- [Wix CSV](https://github.com/TryGhost/migrate/tree/main/packages/mg-wix-csv)
- [WordPress API](https://github.com/TryGhost/migrate/tree/main/packages/mg-wp-api)
- [WordPress XML](https://github.com/TryGhost/migrate/tree/main/packages/mg-wp-xml)

## Install

Migrate is a set of command line tools, install them globally:

`npm install --global @tryghost/migrate`

## Usage

Run `migrate --help` to see a list of available commands.

Basic usage is `migrate [source] source-info`:

E.g.

`migrate medium --pathToZip /path/to/export.zip`

`migrate wp-api --url https://mywpsite.com`

Each source comes with optional flags to customise the migration:

`migrate [source] --help` will give more detail

## Develop

This is a mono repository, managed with [Nx](https://nx.dev/) and pnpm workspaces.

1. `git clone` this repo & `cd` into it as usual
2. `pnpm install` to install all dependencies

## Run

To make sure the TypeScript packages are built (immediately and after file changes), use

```sh
pnpm build:watch
```

Or run `pnpm build` once if you don't need the watching.

To run a local development copy, `cd` into this directory, and use `pnpm dev` instead of `migrate` like so:

```sh
pnpm dev [source]
```

## Test

- `pnpm lint` runs oxlint and checks formatting with oxfmt
- `pnpm format` reformats all files with oxfmt
- `pnpm test` runs lint and tests

## Dependency management

[Knip](https://knip.dev/) is used to find unused dependencies, exports, and files across the monorepo. Run it with:

```sh
pnpm knip
```

Some dependencies are intentionally kept despite not being directly imported (e.g. optional peer dependencies like `sharp`). These are listed in `knip.json` under `ignoreDependencies` for the relevant workspace.

## Publish

Packages are published to npm automatically via GitHub Actions using OIDC trusted publishers — no npm token is needed.

### How to release

1. Run `pnpm ship` locally to interactively version bump, tag, and push to git
    - Uses `nx release` under the hood — prompts per-package for the bump level
    - Also updates any packages which depend on changed packages
2. The push to `main` triggers the [publish workflow](.github/workflows/publish.yml), which builds and publishes all bumped packages to npm

You can also trigger a dry-run from the [Actions tab](https://github.com/TryGhost/migrate/actions/workflows/publish.yml) to preview what would be published without actually publishing.

### Releasing a single package

To version one package instead of the whole monorepo, pass `--projects`:

```sh
pnpm ship --projects=@tryghost/mg-context
```

You are prompted for the bump level — major, minor, patch, or a custom exact version — for that package alone. Anything depending on it is then bumped a patch automatically, so the published dependents point at the new version rather than the old one. Releasing `mg-context`, for example, also releases `mg-ghost-api`, `mg-queue` and `migrate`.

The prompt starts on `major`, so arrow down to the bump you want rather than pressing enter.

Preview the whole thing first with `--dry-run`, which writes and pushes nothing:

```sh
pnpm ship --projects=@tryghost/mg-context --dry-run
```

The publish workflow skips any version already on npm, so only the packages bumped here are published.

### First release of a new package

When publishing a package for the first time:

1. Create the package in `packages/` (see CLAUDE.md for the template)
2. Set `"version": "0.0.0"` in its `package.json`
3. Commit and merge to `main`
4. From the repo root, version, tag, and push just the new package:
    ```sh
    pnpm ship:first-release --projects=@tryghost/mg-<name>
    ```
5. Manually publish the package to npm (CI can only update packages that already exist on npm):
    ```sh
    cd packages/mg-<name>
    pnpm build && npm publish --access public

# If the package has a prerelease tag, add --tag pre
    pnpm build && npm publish --access public --tag pre
    ```
6. Register the package as a trusted publisher so CI can handle future releases:
    ```sh
    npm trust github <package-name> --repo TryGhost/migrate --file publish.yml --allow-publish --yes

# Example:
    npm trust github @tryghost/mg-example-package --repo TryGhost/migrate --file publish.yml --allow-publish --yes
    ```

migrate

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README