Project contracts

Registry schema and deploy contracts

alchemy.new reads a versioned alchemy.new.jsonc file at the project root. That file is the project contract. The live JSON Schema is the machine source of truth. This page describes schema version 1.

Independent project

alchemy.new is not affiliated with Alchemy at alchemy.run. It uses Alchemy as the deployment engine.

Project manifest

Place alchemy.new.jsonc at the repository root for a Git project, or at the package root for an npm project. The file can use JSON with comments. The app rejects a missing or invalid manifest.

Set $schema to https://alchemy.new/schema/v1/project.json so editors can validate the file.

Schema fields

The tables below come from the live schema at /schema/v1/project.json. Do not add fields that the schema does not declare. Unknown fields fail validation.

ProjectManifest fields

Field	Required	Description
`$schema`	Optional	JSON Schema URL for editors. Use the live versioned schema URL.
`schemaVersion`	Required	Schema version. The only accepted value is 1.
`id`	Required	Stable project identifier.
`name`	Required	Display name on alchemy.new.
`description`	Required	Short project summary.
`publisher`	Required	Publisher identity object.
`source`	Required	Git source object or npm source object.
`deployment`	Required	Entrypoint, providers, and default stage.
`parameters`	Required	Form inputs. An empty array is valid.
`tags`	Optional	Search and display labels.
`website`	Optional	Project website.

Publisher

publisher is a required object. Only name is required inside that object.

ProjectPublisher fields

Field	Required	Description
`name`	Required	Publisher display name.
`github`	Optional	GitHub organization or user.
`website`	Optional	Publisher website.

Deployment

deployment names the Alchemy entrypoint and the default run. packageManager is optional in the schema. The runner currently selects Nub or Bun from the project lockfile.

ProjectDeployment fields

Field	Required	Description
`entrypoint`	Required	Repository-relative Alchemy entrypoint. npm wrappers write alchemy.run.ts and import the package export.
`packageManager`	Optional	Declared installer, nub or bun. The runner currently selects the installer from the project lockfile.
`providers`	Required	Supported providers. Allowed values are cloudflare, aws, and other.
`defaultProvider`	Required	Default provider. Allowed values are cloudflare, aws, and other.
`defaultStage`	Required	Default Alchemy stage.

Git and npm sources

source is one Git object or one npm object. The two shapes do not mix.

Git source

The repository must contain the declared Alchemy entrypoint. Direct manifest loads currently support GitHub repositories. The runner clones the repository into an isolated sandbox. A private repository can use a one-run source token on the deployment request.

GitSource fields

Field	Required	Description
`kind`	Required	Source kind. The value must be git.
`url`	Required	HTTPS repository URL.
`ref`	Optional	Branch, tag, or commit. Direct GitHub loads use HEAD when this field is absent.
`token`	Optional	One-run token for a private repository. Do not publish this value in the manifest. Send it only with the deployment request. Share links remove it.

npm source

The npm package must export a default Alchemy Stack from the declared export path. alchemy.new writes a wrapper repository with package.json, alchemy.run.ts, and a resolved lockfile. The wrapper keeps the npm dependency so the user can update it later.

NpmSource fields

Field	Required	Description
`kind`	Required	Source kind. The value must be npm.
`packageName`	Required	npm package name.
`version`	Optional	Package version. Direct loads use latest when this field is absent.
`exportPath`	Optional	Package export that returns the default Alchemy Stack. The runner uses ./alchemy when this field is absent.

Parameters

Each parameter declares an environment variable name and a display label. The web form is built from this list. required and secret are required booleans. type is optional.

A select input can declare options. A secret field uses a masked control. Secret values stay out of shared URL state and short links.

ProjectParameter fields

Field	Required	Description
`name`	Required	Exact environment variable name.
`label`	Required	Display label on the form.
`description`	Optional	Help text on the form.
`required`	Required	Boolean that controls form validation.
`secret`	Required	Boolean that marks a secret. The form masks the field and removes the value from URL state and short links.
`type`	Optional	string, number, boolean, or select. The form uses a text field when this field is absent.
`default`	Optional	Public default. The value can be a string, number, or boolean. Do not publish a credential as a default. Registry readers can inspect the manifest.
`options`	Optional	Allowed values for a select input.

Example

This example matches schema version 1. It includes a public string, a secret string, and a select input. The file can include comments when you store it as JSONC.

{
  "$schema": "https://alchemy.new/schema/v1/project.json",
  "schemaVersion": 1,
  "id": "example-stack",
  "name": "Example stack",
  "description": "Deploys the Example service.",
  "publisher": {
    "name": "Example",
    "github": "example-org",
    "website": "https://example.com"
  },
  "source": {
    "kind": "git",
    "url": "https://github.com/example-org/example-stack",
    "ref": "main"
  },
  "deployment": {
    "entrypoint": "alchemy.run.ts",
    "packageManager": "nub",
    "providers": [
      "cloudflare"
    ],
    "defaultProvider": "cloudflare",
    "defaultStage": "prod"
  },
  "parameters": [
    {
      "name": "APP_NAME",
      "label": "Application name",
      "description": "Public name used for deployed resources.",
      "required": true,
      "secret": false,
      "type": "string"
    },
    {
      "name": "API_KEY",
      "label": "API key",
      "description": "Service key for the Example API.",
      "required": true,
      "secret": true,
      "type": "string"
    },
    {
      "name": "REGION",
      "label": "Region",
      "required": false,
      "secret": false,
      "type": "select",
      "default": "us-east",
      "options": [
        "us-east",
        "eu-west"
      ]
    }
  ],
  "tags": [
    "cloudflare",
    "example"
  ],
  "website": "https://example.com"
}

Listing and verification

Submit a repository from the alchemy.new home page. A submission records the repository for review. A submission does not grant verification.

alchemy.new reviews publisher identity in a separate step. After that review, a project can receive a verified badge and a higher search rank. Featured and verified projects rank before unverified projects.

Publishers can prepare a manifest with the publish-to-alchemy-new skill. Validate the file against the live schema before submission.

Deploy links

Open a Git project with an encoded HTTPS repository URL:

https://alchemy.new/?repo=https%3A%2F%2Fgithub.com%2Fexample%2Fproject

Add ref when the default revision is not correct. Open an npm package with npm:

https://alchemy.new/?npm=%40example%2Finfrastructure

The source must contain alchemy.new.jsonc. Direct Git loads currently support GitHub. npm loads read the published package.

Do not put secrets in a URL. The form excludes secret parameters, provider credentials, Git source tokens, and GitHub tokens from query state and short links.