A working sample application lets a developer inspect and run a product integration. Sample apps require the same ownership, testing, and maintenance as other supported code.
Why sample apps matter
- They provide executable evidence of the product behaviour described in prose.
- They reduce TTFHW from “build something from scratch” to “clone and run.”
- They can remain useful. A maintained example repository can serve new users for years.
- They are evaluable. A potential customer or partner can read your sample apps to assess product quality without talking to sales.
- They feed AI assistants. LLMs trained on or referencing public code use your sample apps as reference for how to use your product.
Categories of sample apps
| Type | Purpose | Example |
|---|---|---|
| Quickstart sample | First five minutes | A 50-line script that calls your API and returns visible output |
| Cookbook recipe | Specific use case | ”Build webhooks that trigger Slack messages” |
| Integration sample | Show product working with another product | ”Stripe + Next.js + Vercel” |
| Reference app | Complete working application | A whole chat app, e-commerce app, dashboard |
| Industry vertical sample | Domain-specific | ”Insurance claims processor using our API” |
| Architectural pattern sample | Show best practice | ”Event-driven architecture with our SDK” |
A programme may need several of these categories, depending on its users and sales model. Quickstarts and cookbook entries are common; reference applications and industry-specific samples are less common.
Where to host them
- GitHub. Your
/examplesorexamplesrepo, or per-language repos. - CodeSandbox / StackBlitz embedded in docs.
- One-click deploys (Vercel “Deploy” button, Netlify “Deploy to Netlify” button, Heroku-style buttons).
- In-browser playgrounds (your own product if it supports them).
For most teams, GitHub is the canonical home; embedded sandboxes and one-click deploys are layered on top.
Maintenance is everything
A recurring failure: shipping sample apps and then letting them rot.
- API versions drift. Yesterday’s sample uses today’s deprecated SDK.
- Dependency drift. A 2-year-old example pulls 2-year-old vulnerable dependencies.
- Documentation drift. The blog post that links to it references behaviour that no longer matches the repo.
Every sample app accumulates maintenance work. Plan for it:
- CI on every example repo. If the test fails, the example is broken.
- Quarterly audit. Each sample gets touched at least once a quarter.
- Owner per example. A specific DevRel team member responsible.
- Deprecation policy. Old samples are explicitly retired before they decay unnoticed.
Set the number of supported samples according to the team’s testing and maintenance capacity.
What makes a good sample
- It has one stated purpose. Avoid combining five unrelated features in one demo.
- It is complete. Includes all imports, .env file template, deploy instructions.
- It is readable. Documented; idiomatic; not cleverly optimised at the cost of clarity.
- It is realistic. Uses real-world patterns, not “hello world” toys.
- It works. CI ensures it.
- It is up-to-date. Last commit within the last 90 days, ideally.
Recipe model: Cookbook repositories
Several leading companies operate “cookbook” repositories that house dozens or hundreds of small recipes:
- OpenAI Cookbook (github.com/openai/openai-cookbook).
- Anthropic Cookbook.
- Stripe samples.
- Twilio Code Exchange.
- Algolia Recipes.
The cookbook model divides examples into small, separately testable units with a clear scope.
Reference apps
A reference app is a complete working application that demonstrates a production-relevant use case. Examples:
- Vercel Commerce. A complete e-commerce template.
- Supabase examples. Full-stack auth-included apps in multiple frameworks.
- Stripe SaaS demo. Full subscription-business reference.
Reference apps require more work to build and maintain than recipes. They let evaluators inspect application-level decisions omitted from a quickstart.
Templates and starters
Adjacent to sample apps: templates and starters.
- Next.js templates (vercel.com/templates).
- Astro themes.
- Supabase quickstarts for various stacks.
- Vite templates for various frameworks.
Templates can reduce TTFHW by supplying project structure and configuration. Framework and platform teams should provide them when those defaults can be maintained.
AI-readiness
Sample apps are heavily consumed by AI coding assistants. To make them AI-friendly:
- Public on GitHub (not behind login).
- Permissive licence (MIT, Apache 2.0).
- Clear README describing what the sample does.
- Logical file structure that AI can navigate.
- No half-finished code. A partial example confuses LLMs.
Teams can also structure public sample apps so AI coding assistants can retrieve complete files, dependencies, and setup instructions.
Sample app strategy summary
- Decide what types of samples you need (quickstart, cookbook, integration, reference).
- Pick a hosting pattern (single
/examplesrepo or per-purpose repos). - Assign owners.
- CI every sample.
- Audit quarterly and retire samples that the team will no longer support.
- Optimise for AI ingestion as well as human reading.
- Link samples from docs at every relevant point.