Documentation

How to use Toolistry

Premium AI tools directory template for Next.js — discover, browse, and showcase AI software.. Discover AI tools that move you forward. Full setup guides live in the repo docs/ folder.

Feature Status

Toolistry is a premium AI tools directory template — not a turnkey SaaS. Use three status labels consistently. Full matrix: docs/FEATURE_STATUS.md.

Ready to UseDiscover home, JSON browse, collections, search, detail pages, theme, SEO

Integration ReadySupabase Auth, admin gate, billing checkout + webhook verify, Workers

Requires ImplementationAdmin CRUD, submissions, bookmarks, subscription entitlements

Getting Started

Toolistry is an AI tools directory template by USG Studio, delivered as a source ZIP. Unzip it, install dependencies, and browse curated real-tool demo listings from JSON. Add Supabase and billing keys when you need auth or payments.

# unzip, then install

cd toolistry

npm install

cp .env.example .env.local

npm run dev

Detailed guide: docs/SETUP.md

Demo Content

IMPORTANT — DEMONSTRATION CONTENT ONLY. The AI tool listings, third-party logos, OG images, screenshots, and related example content are for demonstration, testing, and development only. They are not licensed by USG Studio for production use. Replace them before launch. Policy: docs/DEMO_CONTENT_POLICY.md. Checklist: docs/PRODUCTION_CHECKLIST.md.

Licensing

Commercial use, deep customization, client projects, and monetized End Products are allowed. Reselling the original template (or a superficial reskin) is not. Third-party fonts, icons, and packages keep their own licenses. Summary: docs/LICENSING.md. Full draft: LICENSE.

Environment

Copy .env.example to .env.local. Without keys, the public directory still works from JSON.

NEXT_PUBLIC_SITE_URLSite origin (sitemap, auth redirects, billing returns)

NEXT_PUBLIC_SUPABASE_*Auth — see docs/SUPABASE.md

BILLING_PROVIDER + secretsPayments — see docs/BILLING.md

Supabase

Auth is wired to Supabase Auth when NEXT_PUBLIC_SUPABASE_* keys are set. Without keys, browse still works and auth returns 503 AUTH_NOT_CONFIGURED. Admin requires an user_roles admin row (see docs/SUPABASE.md).

POST/api/auth/registerSupabase sign-up (or 503 if unconfigured)

POST/api/auth/loginSupabase sign-in (or 503 if unconfigured)

POST/api/auth/logoutSupabase sign-out

POST/api/auth/refreshSession claims check

GET/auth/callbackEmail / OAuth code exchange

Apply supabase/migrations/20261013120000_init_directory_skeleton.sql then bootstrap admin with sql/supabase-bootstrap-admin.sql.

Billing

Set BILLING_PROVIDER to polar (default), stripe, or lemon_squeezy, plus that provider’s keys. Without keys, checkout returns 503 BILLING_NOT_CONFIGURED. Guide: docs/BILLING.md.

GET/pricingUpgrade UI

POST/api/billing/checkoutCreate checkout session

POST/api/billing/portalCustomer portal

POST/api/billing/webhookProvider webhooks

Customising

Keep the design system (tokens + components/ui). Change product UI, brand, categories, and JSON freely. Full path: docs/SETUP.md.

Branding / copylib/brand.ts

Logo assetpublic/toolistry-logo.png

Theme tokens (keep)app/globals.css

Categorieslib/categories.ts

Listings (JSON)lib/tools-data.json (replace before production)

Feature statusdocs/FEATURE_STATUS.md

Licensingdocs/LICENSING.md

Demo policydocs/DEMO_CONTENT_POLICY.md

Supabase setupdocs/SUPABASE.md

Billing setupdocs/BILLING.md

Workers deploydocs/WORKERS.md

Deployment

Local Node or Cloudflare Workers via vinext. Rename the Worker in wrangler.jsonc before production. After go-live, update Supabase Auth URLs and billing webhooks. Guide: docs/WORKERS.md.

# Node

npm run build && npm run start

# Workers

npm run preview:vinext

npm run deploy:vinext

Set NEXT_PUBLIC_SITE_URL for sitemap and robots. Run npm run validate:production-content -- --production before launch. License: LICENSE.