Skip to main content

Start from an AdonisJS 7 app

Already have one? Skip ahead. Otherwise the API starter kit is a good base:
Terminal
AdonisJS 7 runs on Node 24 or later, and the SDK on Node 26.12.1 or later, so use 26.12.1+. Every kit starts on SQLite; to use PostgreSQL or MySQL, see Lucid’s setup.

Point the @fetchski scope at your site

Your own site serves the @fetchski packages, and any API key from it lets you in. In your project’s folder (beside its package.json), make a file named .npmrc holding these two lines:
.npmrc
The first line says @fetchski packages come from your site; the second is the key to sign in with. Put your site’s address in both lines (set your site in the bar under this page’s title and the example shows it), and paste your whole key in place of fsk_acme_…. Write the key itself, never a variable or a value from .env: npm and pnpm don’t read .env, and pnpm refuses a variable here.
Any API key from your site works, the same one your app uses included: its scopes and signing mode don’t matter for installing, only that it’s switched on and not past its expiry date. No key yet? Make one in the CMS under API Keys (Authentication).
Then keep the file out of git. Add this line to the project’s .gitignore (make the file if there isn’t one):
.gitignore
.npmrc now holds a key to your site: never commit it. If git already tracks a .npmrc, stop tracking it with git rm --cached .npmrc. Keep these lines in this project’s .npmrc only, never in the .npmrc in your home folder. In CI, write the same file from a secret before installing.

Install the package and the SDK

In a terminal, in the same folder as the .npmrc, run the line for the package manager your project uses:
401 Unauthorized? Your site refused the key in .npmrc: it’s mistyped or cut short, switched off, or past its expiry date. Check too that .npmrc sits in the folder you ran the command in.
The package fits the SDK into AdonisJS; the SDK is its peer, so your app holds the one copy both use. Use the package manager your app already uses.
pnpm 11 skips a release on its first day: TypeScript → Installation has the setting that takes each @fetchski release at once.

Configure it

Terminal
It asks for the site’s URL, its API key and the key’s signing secret (leave it empty for a token-only key), reads the site’s slug from the key, and writes:

config/attract.ts

The site, by its slug, and the options every call shares.

.env and start/env.ts

FETCHSKI_ATTRACT_SITE, _URL, _API_KEY and _SIGNING_SECRET, each checked at boot.

adonisrc.ts

The provider, which puts the client in the container, and the attract:* commands.

.env.example

The same names, the key and secret left empty.
A malformed URL, key or secret writes nothing. Then check the site answers:
Terminal
Configure once, at the prompts: the key and secret are hidden as you type. A deploy or CI run doesn’t run configure again; it sets FETCHSKI_ATTRACT_SITE, _URL, _API_KEY and _SIGNING_SECRET in the environment from its own secret store. (--url, --key and --secret exist, but a flag’s value lands in shell history and is visible to other processes; given --url and --key, a missing --secret means a token-only key.)
Rather keep the key out of .env? Store it sealed in a table instead (see Key in the database):
Terminal

Give your coding agent the skill

Terminal
The SDK’s Agent Skill, so your agent calls the SDK the way these guides do.

Requirements

AdonisJS 7

The provider, the config file and the Ace commands. Lucid only for the key in the database.

Node 26.12.1+

The SDK’s floor: earlier releases carry severe security vulnerabilities.

Japa 5

For fakeAttract() in your tests: the runner every AdonisJS 7 kit ships.

Next: configuration

The generated config/attract.ts, the default site, and more sites.