{"id":18517247,"url":"https://github.com/cameronapak/freedom-stack","last_synced_at":"2025-04-04T12:05:46.067Z","repository":{"id":226709418,"uuid":"758797342","full_name":"cameronapak/freedom-stack","owner":"cameronapak","description":"A full-stack Astro starter kit that feels freeing and is free. Ready for use, and even better when using Cursor's IDE.","archived":false,"fork":false,"pushed_at":"2025-03-20T15:05:27.000Z","size":2747,"stargazers_count":151,"open_issues_count":8,"forks_count":7,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-01T23:13:52.535Z","etag":null,"topics":["alpinejs","astro","astro-db","astrojs","astrojs-boilerplate","astrojs-template","full-stack","htmx","libsql","saas-boilerplate","saas-starter-kit","turso"],"latest_commit_sha":null,"homepage":"https://freedom.faith.tools","language":"Astro","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cameronapak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-17T05:23:33.000Z","updated_at":"2025-03-31T16:42:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"bb773601-e34b-4c37-b65b-a9a332f17e75","html_url":"https://github.com/cameronapak/freedom-stack","commit_stats":null,"previous_names":["cameronapak/freedom-stack"],"tags_count":11,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronapak%2Ffreedom-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronapak%2Ffreedom-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronapak%2Ffreedom-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cameronapak%2Ffreedom-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cameronapak","download_url":"https://codeload.github.com/cameronapak/freedom-stack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174403,"owners_count":20896075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpinejs","astro","astro-db","astrojs","astrojs-boilerplate","astrojs-template","full-stack","htmx","libsql","saas-boilerplate","saas-starter-kit","turso"],"created_at":"2024-11-06T17:01:09.475Z","updated_at":"2025-04-04T12:05:46.040Z","avatar_url":"https://github.com/cameronapak.png","language":"Astro","funding_links":[],"categories":["Tools"],"sub_categories":["Community"],"readme":"# Freedom Stack\n\nA modern, type-safe web development stack using Astro, TypeScript, HTMX, Alpine.js, and more.\n\n\u003e [!TIP]\n\u003e [Turso](https://tur.so/freedomstack) has a generous free tier for database hosting and management. And, when it's time to scale, use the code `FREEDOMSTACK` for a discount on paid plans.\n\n## Get Started 🚀\n\n### 1. Create Your Project\n\nYou can create a new Freedom Stack project using npm:\n\n```bash\n# Create a new project\nnpx create-freedom-stack my-app\n\n# Navigate to the project directory\ncd my-app\n\n# Set up your database\nnpm run db:setup\n\n# Start the development server\nnpm run dev\n```\n\nYour development server will be running on [`localhost:4321`](http://localhost:4321).\n\n### 2. Environment Variables\n\nThe project will automatically create a `.env` file with a generated `BETTER_AUTH_SECRET`. You'll need to set these additional variables:\n\n```env\n# Astro DB - LibSQL (required) - Your database\nASTRO_DB_REMOTE_URL=\"\"    # Added by npm run db:setup\nASTRO_DB_APP_TOKEN=\"\"     # Added by npm run db:setup\n\n# Better Auth (required)\nBETTER_AUTH_SECRET=\"\"     # Auto-generated during setup\nBETTER_AUTH_URL=\"http://localhost:4321\"\n\n# Email Configuration (optional) - For sending emails\nMAIL_HOST=\"\"             # SMTP host (e.g., smtp.resend.com)\nMAIL_PORT=\"\"             # SMTP port (e.g., 465)\nMAIL_SECURE=\"\"          # Use TLS/SSL (true/false)\nMAIL_AUTH_USER=\"\"       # SMTP username\nMAIL_AUTH_PASS=\"\"       # SMTP password or API key\nMAIL_FROM=\"\"            # Sender email address\n```\n\n### 3. Have fun!\n\nCreate because you love creating. Make development fun again!\n\n## What's Included\n\n- 🚀 [Astro](https://astro.build) - The web framework for content-driven websites\n- 🎨 [TailwindCSS](https://tailwindcss.com) + [DaisyUI](https://daisyui.com) - Utility-first CSS\n- ⚡ [HTMX](https://htmx.org) - High power tools for HTML\n- 🗄️ [Astro DB](https://docs.astro.build/en/guides/astro-db) - Built-in database with type safety\n- 🔒 [Better Auth](https://better-auth.com) - Simple, secure authentication\n- 🏃‍♂️ [Alpine.js](https://alpinejs.dev) - Lightweight JavaScript framework\n\n# Freedom Stack • Full-Stack Starter Kit\n\n[![Netlify Status](https://api.netlify.com/api/v1/badges/78803fc4-5d36-4efb-82cd-2daeb5684fb6/deploy-status)](https://app.netlify.com/sites/freedom-stack/deploys) [![Github Stars](https://img.shields.io/github/stars/cameronapak/freedom-stack?style=flat-square)](https://github.com/cameronapak/freedom-stack/stargazers)\n\nAn Astro-based full-stack starter kit that feels freeing, and is free. Make development fun again. [See the demo site](https://freedom.faith.tools).\n\nI wanted to provide a stack that's powerful like Ruby on Rails _(\"The One Person Framework\")_, but with the ease and \"vanilla\" web dev feel of Astro.\n\n\u003ca href=\"https://app.netlify.com/start/deploy?repository=https://github.com/cameronapak/freedom-stack\"\u003e\u003cimg src=\"https://www.netlify.com/img/deploy/button.svg\" alt=\"Deploy to Netlify\"\u003e\u003c/a\u003e\n\n![freedom stack](public/og-image.png)\n\n## Learning Resources 📚\n\n### The Frontend Layer\n\nIf you want to learn more about the frontend layer, I recommend the [Astro Web Framework Crash Course by freeCodeCamp](https://www.youtube.com/watch?v=e-hTm5VmofI).\n\n### The Interactivity Layer\n\nIf you want to learn more about Alpine.js, I recommend [Learn Alpine.js on codecourse](https://codecourse.com/courses/learn-alpine-js).\n\n### The Database Layer\n\nIf you want to learn more about the database layer, I recommend learning from [High Performance SQLite course](https://highperformancesqlite.com/), sponsored by [Turso](https://tur.so/freedomstack/).\n\n### The Philosophy Layer\n\nA starter kit like this can save hours, days, or even weeks of development time. However, it's not enough just to have the baseline. You will need to have a philosophy around building a site or web app, so that you can make the most of the tooling and minimize wasting time. I recommend reading Getting Real by 37signals. [It's free to read online](https://books.37signals.com/8/getting-real). _(While the book says a few choice words, it's a great, practical resource for building great software.)_\n\n## Here's What's Included 🔋🔋🔋\n\nOgres have layers. Onions have layers. Parfaits have layers. And, Freedom Stack has layers!\n\n### UI Layer\n\n- [Astro](https://astro.build/) - A simple web metaframework.\n- [Tailwind CSS](https://tailwindcss.com/) - For styling.\n- [Preline UI](https://preline.co/) - Tailwind-based HTML components.\n- [Daisy UI](https://daisyui.com/) - For a Bootstrap-like UI CSS component\n  library, built upon Tailwind.\n- [Lucide Icons](https://lucide.dev/) - For a beautiful icon library.\n\n### Interactivity Layer\n\n- [TypeScript](https://www.typescriptlang.org/) - For type safety.\n- [AlpineJS](https://alpinejs.dev/) - For state management and interactivity.\n- [HTMX](https://htmx.org/) - For sending HTML partials/snippets over the wire.\n\n### Backend Data Layer\n\n- [Astro DB](https://astro.build/db) - Astro DB is a fully managed SQL database\n  that is fast, lightweight, and ridiculously easy-to-use.\n- [Drizzle ORM](https://orm.drizzle.team/) - Use your database without having to know or worry about SQL syntax.\n- [Better Auth](https://better-auth.com/) - For authentication.\n\n### Bonus Layer\n\n- A well-prompted `.cursorrules` file for [Cursor's AI IDE](https://cursor.com/) to be a friendly guide helping you using this stack easier.\n\n---\n\n## Host Your Project ☁️\n\nHost your site with [Netlify](https://netlify.com) in under a minute.\n\nFirst, you must login to Netlify:\n\n```bash\nnpm run host:login\n```\n\nThen, you can deploy your site with:\n\n```bash\nnpm run host:deploy\n```\n\n\u003e [!IMPORTANT]\n\u003e Remember to set the environment variables in Netlify so that it builds successfully.\n\n[Learn more about hosting Astro sites on Netlify](https://docs.astro.build/en/guides/deploy/netlify/).\n\n---\n\n## Send Emails\n\n## Email Configuration 📧\n\nFreedom Stack includes a pre-configured email service using Nodemailer. This allows you to:\n\n- Send transactional emails\n- Use any SMTP provider\n- Handle email templates\n- Maintain type safety\n\n### Setting up Email\n\n1. Configure your environment variables as shown above\n\nSend emails programmatically:\n\n```typescript\nimport { sendEmail } from \"@/lib/email\";\n\nawait sendEmail({\n  to: \"recipient@example.com\",\n  subject: \"Hello!\",\n  html: \"\u003ch1\u003eWelcome!\u003c/h1\u003e\"\n});\n```\n\n### Email Providers\n\nWhile you can use any SMTP provider, we recommend [Resend](https://resend.com) - Modern email API with generous free tier.\n\n\u003e [!TIP]\n\u003e Resend offers 100 emails/day free and has excellent developer experience.\n\n---\n\n## Vision ❤️\n\nI dream of a lightweight, simple web development stack that invokes a fun web\nexperience at the cheapest possible maintainance, backend, and server cost. As\nclose to free as possible.\n\n### Core Principles\n\n- **Approachable** — I want those new to web development to feel comfortable\n  using this stack. Things like database management should feel intuitive.\n  Remove barriers of traditional JavaScript frameworks, such as excessive\n  boilerplate code or intense state management. Go back to the basics of web\n  development. (_While this is not vanilla, the dev experience will feel very\n  natural._)\n- **Flow-able** — Use an HTML-first approach, where almost all of the work is\n  done on the DOM layer: styling, structuring, and interactivity. An opinionated\n  stack helps you avoid analysis paralysis of trying to decide what tooling to\n  pick or how to put things together. Instead, spend your thinking time\n  building. This simple stack helps you focus and get in the flow of code\n  faster. Fast setup. Fast building. Fast shipping.\n- **Pocket-friendly** — Using this stack will be financially maintainable to\n  anyone, especially indie hackers and those creating startup sites / web apps.\n\n## Showcase 🏆\n\n- [faith.tools](https://faith.tools)\n- [freedom](https://freedom.melos.church)\n- [Be Still](https://ft-be-still.netlify.app)\n- [kit](https://kit.faith.tools)\n\nHave a project that uses Freedom Stack? [Open a PR](https://github.com/cameronapak/freedom-stack) to add it to the list!\n\n## Available Scripts ⚡\n\n| Command                     | Description                                      |\n| --------------------------- | ------------------------------------------------ |\n| `npm run dev`               | Start the development server                     |\n| `npm run dev:host`          | Start development server accessible from network |\n| `npm run build`             | Build the production site with remote database   |\n| `npm run preview`           | Preview the built site locally                   |\n| `npm run format`            | Format all files using Prettier                  |\n| `npm run packages:update`   | Update all packages to their latest versions     |\n| `npm run db:update-schemas` | Push database schema changes to remote database  |\n\n## Contributions 🤝\n\nContributions welcomed. Please\n[open an issue](https://github.com/cameronapak/astwoah-stack/issues) if you'd\nlike to contribute.\n\n\u003ca href=\"https://github.com/cameronapak/freedom-stack/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=cameronapak/freedom-stack\" /\u003e\n\u003c/a\u003e\n\nMade with [contrib.rocks](https://contrib.rocks).\n\n---\n\n## License 📜\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Code of Conduct 📜\n\nSee the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) file for details.\n\n---\n\nFreedom Stack is made with 🕊️ by [Cameron Pak](https://cameronpak.com), brought to you by [faith.tools](https://faith.tools).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameronapak%2Ffreedom-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcameronapak%2Ffreedom-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameronapak%2Ffreedom-stack/lists"}