---
name: publish-placeholder-package
description: Publish a placeholder npm package at version 0.0.0 so package names are reserved and npm OIDC permissions can be configured before CI publishing. Use when creating a brand-new package that is not ready for full release.
---

# Publish Placeholder Package

## Overview

Use this skill to publish a minimal placeholder package to npm at `0.0.0`. This is used to reserve the package name and unblock npm-side OIDC configuration for CI publishing.

## Workflow

1. Confirm publish target.

- Collect:
  - npm package name (for example, `@remix-run/my-package`)
  - package directory in repo (for example, `packages/my-package`)
- Validate the package does not already exist at `0.0.0`:

```sh
npm view <package-name>@0.0.0 version
```

- If it already exists, stop and report that no placeholder publish is needed.

2. Build a temporary placeholder package outside the repo.

- Always publish from a temp directory to avoid shipping real package files by mistake.
- Create the temp directory and write a minimal `package.json`:

```sh
tmp_dir="$(mktemp -d)"
cd "$tmp_dir"

cat > package.json <<'JSON'
{
  "name": "<package-name>",
  "version": "0.0.0",
  "description": "Placeholder package for Remix CI/OIDC setup",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/remix-run/remix.git",
    "directory": "<repo-package-dir>"
  },
  "publishConfig": {
    "access": "public"
  }
}
JSON
```

- Add a short README:

```sh
cat > README.md <<'MD'
# Placeholder Package

This package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions.
MD
```

3. Ensure npm auth is valid (expect re-auth/OTP).

- Check session:

```sh
npm whoami
```

- If not authenticated, run:

```sh
npm login
```

- Expect npm to require a fresh login and/or one-time password. If prompted for OTP, request it from the user and continue.

4. Publish the placeholder.

- Publish with public access:

```sh
npm publish --access public
```

- If the account enforces 2FA for writes, publish with OTP:

```sh
npm publish --access public --otp <code>
```

5. Wait for the placeholder to appear on npm, then configure trusted publishing.

- New package names may take a short time to become visible in the registry after `npm publish`.
- Poll until `0.0.0` resolves before running `npm trust`:

```sh
for attempt in $(seq 1 18); do
  version=$(npm view <package-name>@0.0.0 version --silent 2>/dev/null || true)
  if [ "$version" = "0.0.0" ]; then
    break
  fi

  echo "Waiting for <package-name>@0.0.0 to appear on npm..."
  sleep 10
done

if [ "$version" != "0.0.0" ]; then
  echo "Package did not appear on npm in time"
  exit 1
fi
```

- As soon as it resolves, configure the GitHub Actions trusted publisher from the same local machine where you published the placeholder:

```sh
npm trust github <package-name> --repo remix-run/remix --file publish.yaml --yes
```

- This follow-up should be done immediately after placeholder publish while local npm auth is already available.

6. Verify and report.

- Verify the published version:

```sh
npm view <package-name>@0.0.0 version
```

- Report:
  - package name
  - published version (`0.0.0`)
  - confirmation that `npm trust github` succeeded for `.github/workflows/publish.yaml`

7. Clean up temp files.

```sh
rm -rf "$tmp_dir"
```

## Notes

- Keep placeholder publish minimal. Do not publish full source code for this step.
- This is a one-time bootstrap step. Normal releases should continue through CI.
- Do not stop after `npm publish`; the placeholder is only fully ready once `npm trust github` has been configured.