Awesome Apptly

Directory website for Apptly Software's open-source projects, live at https://awesome-apptly.com.

Stack

Layer	Technology
Framework	Nuxt 4 + Nuxt Content 3
Hosting	Cloudflare Workers (cloudflare-module preset)
Database	Cloudflare D1 (content database)
Cache	Cloudflare KV (version cache)
Styling	Tailwind CSS 4 + @tailwindcss/typography
Icons	@nuxt/icon + @iconify-json/simple-icons
Badges	badge-maker (self-hosted SVG badges, logos inlined as base64)
Editor	Nuxt Studio ~1.4 (browser-based content editing)
Lint	ESLint 9 + @poupe/eslint-config
CI	GitHub Actions

Content model

Two collections defined in content.config.ts:

Categories (content/categories/*.md)

Each file defines a category. The filename (minus .md) is the slug used in project front matter and URLs. Adding or removing a file updates the Zod enum automatically (derived via readdirSync).

Field	Type	Notes
title	string	display name
description	string	short description
kind	"umbrella" | "language"?	umbrella = project family, language = programming language

Projects (content/projects/*.md)

Field	Type	Values
title	string	inherited from Nuxt Content's page type
description	string	inherited from Nuxt Content's page type
category	enum array	one or more category slugs from content/categories/ (including languages)
repo	string?	source link as github:{owner/repo[/dir]}
licence	string?	SPDX identifier (e.g. MIT, Apache-2.0)
npm	string?	npm package name — self-hosted version badge via /api/badge/npm/
go	string?	Go module path — self-hosted version badge via /api/badge/go/

Branching model

Branch	Purpose
main	Production. Deployed to Cloudflare Workers.
stage	Content staging. Nuxt Studio commits here. Merge to main via PR when ready.

Prerequisites

• Node.js 22
• pnpm (version pinned in package.json packageManager field)

Development

pnpm install
pnpm dev              # runs nuxt cleanup + dev server

pnpm dev runs nuxt cleanup before starting the dev server, removing stale client-side SQL dumps that would cause SPA 404s. The dev server regenerates the content database on startup.

Build and deploy

make build            # pnpm install (if needed) + pnpm build
pnpm build            # build only (assumes deps installed)
pnpm run deploy       # wrangler deploy (not `pnpm deploy` —
                      # pnpm reserves that for workspaces)

Validation

pnpm precommit        # generate + lint (with --fix) + typecheck
pnpm check            # generate + lint (check-only) + typecheck
make tidy             # whitespace fix + lint + spell check

pnpm check is what CI runs. make tidy also fixes trailing whitespace across all file types and runs cspell on markdown.

Both pnpm lint and make tidy require a prior build — ESLint imports .nuxt/eslint.config.mjs, which is generated by nuxt generate, nuxt build, or nuxt prepare.

Environment variables

Copy .env.template to .env.local and fill in the values. Secrets are uploaded to Cloudflare via wrangler secret bulk .env.local.

Known constraints

• nuxt-studio is pinned to ~1.4 because 1.5.x breaks the cloudflare-module build (sharp wasm resolution issue).
• pnpm clean fails if node_modules is already gone.