@adonisjs/packages 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +128 -2
  2. package/db.json +2831 -0
  3. package/package.json +45 -4
package/README.md CHANGED
@@ -1,3 +1,129 @@
1
- # Temporary Holding Version
1
+ # AdonisJS Packages
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Discover the AdonisJS packages to add database, auth, ORM, queue, payment and more integrations into your AdonisJS application.
4
+
5
+ - 🔗 [Packages listing](https://adonisjs.com/packages)
6
+ - 📖 [Package author guide](https://docs.adonisjs.com/guides/packages-development)
7
+
8
+ ## Packages Database
9
+
10
+ Metadata of AdonisJS packages are maintained in [yml](https://en.wikipedia.org/wiki/YAML) files inside the [./packages](./packages) directory and automatically synced from upstream to fetch latest information.
11
+
12
+ ### Add/Update a package
13
+
14
+ ```bash
15
+ pnpm sync <name> <repo>
16
+ ```
17
+
18
+ Example: `pnpm sync lucid adonisjs/lucid`
19
+
20
+ To sync with a branch different than the default, suffix the repo with `#repo-branch`, example: `pnpm sync lucid adonisjs/lucid#next`.
21
+
22
+ ### Contribution
23
+
24
+ - If you feel a package is missing, please create a new [issue](https://github.com/adonisjs-community/packages/issues/new).
25
+ - If some data is outdated please directly open a pull request.
26
+
27
+ ### Using CDN
28
+
29
+ Compiled JSON data is available from following CDNs:
30
+
31
+ - **jsdelivr:** https://cdn.jsdelivr.net/npm/@adonisjs/packages@latest/db.json
32
+ - **unpkg:** https://unpkg.com/@adonisjs/packages@latest/db.json
33
+
34
+ ### Using npm package
35
+
36
+ You can use the `@adonisjs/packages` package by installing it in your project:
37
+
38
+ ```bash
39
+ # npm
40
+ npm install @adonisjs/packages
41
+
42
+ # pnpm
43
+ pnpm add @adonisjs/packages
44
+ ```
45
+
46
+ Then you can directly import the list of packages:
47
+
48
+ ```ts
49
+ import db from '@adonisjs/packages'
50
+ // ^? { generatedAt, version, categories, packages }
51
+ ```
52
+
53
+ ### Schema
54
+
55
+ | Field | Auto sync | Description |
56
+ | ------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
57
+ | `name` | No | Canonical name. Must match the filename. |
58
+ | `description` | Yes | Short description, pulled from upstream `package.json`. |
59
+ | `repo` | No | GitHub repository. Format is `org/name` or `org/name#branch`. |
60
+ | `npm` | Yes | NPM package name. |
61
+ | `icon` | No | Icon of the package from the [./icons](./icons) directory. |
62
+ | `github` | Yes | GitHub URL, derived from `repo`. |
63
+ | `website` | No | Project / docs URL. |
64
+ | `category` | No | One of the [supported categories](./lib/categories.ts). |
65
+ | `type` | Yes | `official` (for [adonisjs](https://github.com/adonisjs/)) or `3rd-party`. |
66
+ | `maintainers` | Yes (if empty) | List of maintainers — each item has `name`, `github`, optional `twitter` / `bluesky`. Manual entries are preserved. |
67
+ | `compatibility` | No | `compatibility.adonis` is a map of AdonisJS major (e.g. `6`, `7`) → label (`6.x`, `7.x`). Keys declare supported majors. |
68
+ | `aliases` | No | Optional list of old names. |
69
+ | `lastCommitAt` | Bot | ISO date of default-branch HEAD commit. |
70
+ | `lastReleaseAt` | Bot | ISO date of latest npm publish. |
71
+ | `latestNpmVersion` | Bot | Latest npm version on `latest` dist-tag. |
72
+ | `status` | Bot | `healthy` / `stale` / `archived`. Bot auto-sets `archived`/`healthy`; `stale` only via the dashboard PR. |
73
+
74
+ ## Maintenance
75
+
76
+ ### Auto update all current packages
77
+
78
+ ```bash
79
+ pnpm sync
80
+ ```
81
+
82
+ ### Generate `db.json`
83
+
84
+ ```bash
85
+ pnpm build
86
+ ```
87
+
88
+ ### Configure npm publishing
89
+
90
+ The release workflow publishes public packages from `v*` tags using npm trusted publishing. It runs on GitHub-hosted runners with Node.js 24 and requires no `NPM_TOKEN` secret.
91
+
92
+ 1. If `@adonisjs/packages` does not exist on npm, sign in with an account that can publish under `@adonisjs`. Run `pnpm install --frozen-lockfile`, `pnpm check`, and `npm pack --dry-run`. Inspect the package contents, then run `npm publish --access public` to publish the initial version.
93
+ 2. In the package's npm settings, add a GitHub Actions trusted publisher with organization `adonisjs-community`, repository `packages`, and workflow filename `release.yml`. Leave the environment blank and allow direct `npm publish`.
94
+ 3. Complete the first OIDC publication within two days of creating the trusted publisher. After it succeeds, enable "Require two-factor authentication and disallow tokens" in the npm publishing settings.
95
+
96
+ See the [npm trusted publishing documentation](https://docs.npmjs.com/trusted-publishers) for account requirements and troubleshooting.
97
+
98
+ ### Publish a new version
99
+
100
+ From a clean, up-to-date `main` checkout, run:
101
+
102
+ ```bash
103
+ pnpm check
104
+ pnpm exec tsc --noEmit
105
+ npm version patch
106
+ git push origin main
107
+ git push origin "v$(node -p "require('./package.json').version")"
108
+ ```
109
+
110
+ Pushing the tag publishes the package. The tag must match the version in `package.json`. Published versions cannot be reused, including the version published manually during setup. The weekly healthcheck updates metadata but does not yet publish npm versions.
111
+
112
+ ## Healthiness bot
113
+
114
+ A weekly GitHub Action keeps the bot-owned metadata fields (`lastCommitAt`, `lastReleaseAt`, `latestNpmVersion`, `status`) fresh by auto-committing directly to `main`. It also maintains a long-lived **Dependency Dashboard** issue (label: `bot:dashboard`) listing actionable curation calls — currently only `Mark as status: stale` proposals (no compat-range or "claim adonis N support" suggestions, since only the package author can verify those).
115
+
116
+ Tick the checkbox in the dashboard issue → a `bot/healthcheck/<id>` PR opens with that single change.
117
+
118
+ ### One-time setup (maintainer)
119
+
120
+ 1. Repo Settings → Actions → General → **Workflow permissions**: Read and write permissions; check **Allow GitHub Actions to create and approve pull requests**.
121
+ 2. Create a GitHub App scoped to this repo with: Contents read/write, Issues read/write, Pull requests read/write, Metadata read. Install on the repo.
122
+ 3. Add two repo secrets: `BOT_APP_ID` and `BOT_APP_PRIVATE_KEY`.
123
+ 4. Pre-create labels `bot:dashboard` and `bot:auto-pr` on the repo.
124
+
125
+ Trigger `Healthcheck (weekly)` manually via the Actions tab to kick off the first run.
126
+
127
+ ## License
128
+
129
+ [MIT](./LICENSE) — Made with ❤️ by the AdonisJS community