Skip to content
wgw-deploy

Concepts

Concepts

Section titled “Concepts”

Deploy target

Section titled “Deploy target”

The CLI resolves two paths before deploying:

  • cwd: the project root. It defaults to the process current working directory.
  • dir: the deploy target. It defaults to dist.

Relative --dir values are resolved from cwd.

Terminal window
npx wgw-deploy
npx wgw-deploy --dir public
npx wgw-deploy --cwd /path/to/app --dir build

The target can be a directory or a single file. Directory deploys walk the target recursively, skip symlinks, and ignore common project/cache directories such as .git, node_modules, .cache, .turbo, .wrangler, and coverage.

Project hash

Section titled “Project hash”

The local project identity is a hash of the resolved cwd and the deploy directory. The source formula uses:

  • the literal namespace wgw-project-v1
  • the SHA-256 hash of cwd
  • the SHA-256 hash of the normalized deploy directory

The project hash is not the public project name. It is the local key used to find the matching project state for future commands.

Changing either cwd or dir changes the project hash. To keep deploying to the same project, use the same working directory and deploy directory, or pass the same --cwd and --dir values every time.

Project state

Section titled “Project state”

The CLI stores project state on the local machine. The config root is resolved in this order:

  1. WGW_DEPLOY_CONFIG_DIR
  2. $XDG_CONFIG_HOME/wgw-deploy
  3. ~/.config/wgw-deploy

Project state is written to:

<config-root>/projects/<projectHash>/state.json

That file stores the public project metadata, API token, resolved cwd, deploy directory, and update time. wgw-deploy --list reads the local state directory and prints the tracked projects.

Deploy replay state is stored separately in the cache root, under deploys/<projectSlug>/. It is used to detect unchanged local files and report cached deploys.

Project slug and default domain

Section titled “Project slug and default domain”

When the CLI creates a new remote project, the service assigns a generated project slug. The default domain is:

https://<projectSlug>.wgw.lol/

The project metadata tracks the current domain, the latest revision ID, previous revision IDs, creation time, and expiration when applicable.

Live URL

Section titled “Live URL”

The live URL always points at the latest revision for the current domain.

https://<domain>/

After a new deploy finalizes, the service updates the project manifest so the live URL serves the new latest revision.

Revision ID

Section titled “Revision ID”

A revision ID is derived from the deploy manifest. The service hashes the manifest JSON and uses the first 16 hex characters as the revision ID.

If the manifest does not change, the revision ID stays the same. If the deployed files change, the manifest changes and the next deploy gets a new revision ID.

Pinned revision URL

Section titled “Pinned revision URL”

Pinned revision URLs keep serving a specific revision.

For generated wgw.lol project domains and assigned wgw.lol subdomains, the pinned URL uses a revision subdomain:

https://<project-or-domain-prefix>--<revisionId>.wgw.lol/

For custom domains, the pinned URL uses the _rev path segment:

https://<custom-domain>/_rev/<revisionId>/

The CLI prints the pinned URL as pinned in text output and as revisionUrl in JSON output.

Domains

Section titled “Domains”

The --domain flag assigns a domain to the locally tracked project. A domain can be:

  • a wgw.lol subdomain
  • a custom hostname

For a custom hostname, the CLI returns a CNAME record. Create that DNS record before relying on the custom domain. For a wgw.lol subdomain, the service can serve it directly.

Domain assignment is separate from deploying files. After changing the domain, run npx wgw-deploy to publish a new file revision if the output changed.

Limits

Section titled “Limits”

The current deploy limits are:

  • maximum files: 5,000
  • maximum file size: 10 MB