Installation

This page installs hpy and creates a project. HappyView itself is not installed separately: hpy downloads the version a project names when it runs the project.

hpy is in beta and HappyView v3 is in alpha. hpy happyview create writes a HappyView version into the project it creates.

Before you start

• macOS or Linux. On Windows, use WSL and follow the Linux steps inside it: running a project locally is not supported on Windows itself.
• An atproto account to develop with, such as a Bluesky account. Use a test account rather than a personal one, because a project running locally writes to that account’s real PDS (Running locally). pds.rip issues sandbox accounts on the real network and deletes them after 7 days.

Install hpy

hpy has no stable release yet, so install it from its beta channel:

Homebrew

brew

brew install happyproto/tap/hpy-beta

Install script

curl

curl -fsSL https://happyproto.github.io/cli/install-beta.sh | sh

The install script puts hpy in ~/.cargo/bin; open a new terminal if it isn’t on your PATH yet. Verify the installation:

hpy

hpy --version

hpy update keeps it up to date on the beta channel. For apt, dnf and building from source, see hpy’s own install instructions.

Create a project

hpy

hpy happyview create --name my-app

--name is the directory to create. create then asks four things:

Prompt	What to answer
Superadmin DID	The DID (did:plc:…) of the account you’ll develop with. That account holds the superadmin privilege on the local instance. If you’ve signed in with hpy registry login, that account’s DID is offered. To find an account’s DID, look its handle up at pdsls.dev.
Interpreters	The languages you’ll write scripts in: Lua, JavaScript or TypeScript. Lua is selected by default.
Libraries	The libraries your scripts will use, such as happyview.db for reading records. You can add more later with hpy happyview add.
App name	Your app’s name, shown in the dashboard. It defaults to the directory’s name.

create writes the files listed under Generated files. HappyView and the plugins are downloaded the first time hpy runs the project.

An interpreter is a plugin that runs scripts in one language, and a library is a plugin your scripts load to do more, such as reading records. Plugins and libraries covers both.

Generated files

• my-app/

  • happyview.toml
  • happyview.lock
  • .env.example
  • .gitignore
  • .luarc.json
  • src/lexicons/com/example/

    • hello.json
    • hello.lua

• happyview.toml names the HappyView version, the interpreters and libraries, and your instance’s settings.
• happyview.lock pins the exact plugin versions.
• .env.example lists script variables for hpy happyview dev. Copy it to .env and each KEY=value line is available to scripts as ctx.env.KEY. A deployed instance takes script variables from its own settings or environment instead.
• .gitignore keeps .env and the local instance’s .happyview/ directory out of git.
• .luarc.json points an editor at HappyView’s Lua types. A project with JavaScript or TypeScript also gets a tsconfig.json, which does the same for those languages.
• src/lexicons/com/example/hello.json is a query lexicon, and hello.lua beside it is the script that answers it. The script is in the first language you picked.

Project structure describes each file.

Next steps

• Running locally: start your project and call com.example.hello.