Daily Beast Looker Development
Development skill for "The Looker" website - a sub-brand of The Daily Beast that will live at `thelooker.thedailybeast.com`. Built with Astro SSR, deployed to Cloudflare Workers, and designed to eventually scale to power the entire Daily Beast website.
Project Context
This is a content-driven website built with:
**Framework**: Astro with SSR mode (server-side rendering)**Hosting**: Cloudflare Workers via `@astrojs/cloudflare` adapter**UI Components**: Shadcn UI (configured in `components.json`)**Styling**: Tailwind CSS v4 with CSS variables for theming**React Integration**: For interactive components**Content Source**: ArcXP content API (cached in Supabase)Development Workflow
Available Commands
```bash
npm run dev # Start dev server at localhost:4321
npm run build # Build for production to ./dist/
npm run preview # Preview production build locally
npx astro check # Type-check .astro files
```
Before Starting Work
1. **Always ask questions before big decisions** - Don't assume anything about requirements or architecture
2. **Check sample data** in `documentation/` folder for reference structures
3. **Review TASKS.md** to understand current project state and priorities
4. **Test thoroughly** before committing changes
Component Architecture
Follow this specific organization for content blocks:
```
src/
components/
blocks/ # Article content blocks (reusable)
TextBlock.astro
ImageBlock.astro
HeaderBlock.astro
QuoteBlock.astro
ListBlock.astro
ReferenceBlock.astro
OEmbedBlock.astro
CustomEmbedBlock.astro
RawHtmlBlock.astro
layout/ # Site structure
Header.astro # The Looker branded header
Footer.astro # The Looker branded footer
Navigation.astro
ui/ # Shadcn components
features/ # Page-specific components
ArticleLayout.astro
HomepageGrid.astro
TagPageList.astro
```
Content Block Types
Articles from the API contain `content_elements` arrays with these block types:
**Text & Structure**:
`text`: Paragraphs with embedded HTML`header`: Section headers (levels 2, 3)`list`: Ordered/unordered lists`quote`: Pull quotes and blockquotes**Media**:
`image`: Images with captions, credits, metadata`custom_embed`: Video players, section breaks`oembed_response`: YouTube, Twitter/X, Instagram, Facebook, TikTok embeds`raw_html`: DocumentCloud, Truth Social, SoundCloud, other custom embeds**References**:
`reference`: Related story linksAPI Integration
Content Cache API
**Core Endpoints**:
`/collections?content_alias=[alias]` - Get collection by alias (e.g., homepage)`/collections?id=[id]` - Get collection by ID`/stories?canonical_url=[slug]` - Get article by URL slug`/stories?id=[id]` - Get article by ID`/stories/list?tag_slug=[tag]` - List articles by tag`/stories/list?author_slug=[author]` - List articles by author`/sections?id=[id]` - Get section metadata**Query Parameters**:
`fields` - Comma-separated list of fields to include (reduces payload)`limit` & `offset` - Pagination for list endpoints`sort_field` & `sort_direction` - Sorting options**Full API Documentation**: See `documentation/middleware-api.json` (OpenAPI spec)
Environment Variables
Configure in `.env` file (see `.env.example`):
`CONTENT_CACHE_API_URL` - Base URL for content API`CF_ACCESS_CLIENT_ID` - Cloudflare Access authentication`CF_ACCESS_CLIENT_SECRET` - Cloudflare Access secretThird-Party Integrations
**Zephr API** (User Authentication):
API Documentation: https://developer.zuora.com/zephr-api-reference/zephr-public-api/overview/Features: User login/logout, display email in navigation, account pageImplementation: Use as dynamic server island component for user state**Shadcn UI Components**:
Documentation: https://ui.shadcn.com/Already initialized with `components.json` configurationStyle: "new-york" variant with Tailwind CSS v4**IMPORTANT**: Only use out-of-the-box components - do not build custom components from scratch without approval**Planned Integrations**:
Google Tag Manager (GTM) for analytics (The Looker specific container)SEO meta tags and JSON-LD structured dataJW Player for video embedsPath Aliases
TypeScript paths configured in `tsconfig.json`:
`@/*` maps to `./src/*`Shadcn UI aliases in `components.json`:
`@/components` - Component directory`@/lib/utils` - Utility functions`@/components/ui` - Shadcn UI componentsStyling Guidelines
**Mobile-first responsive design** - Design for mobile, enhance for desktopTailwind CSS v4 with the new CSS-first configurationCSS variables for theming (prepared for Daily Beast migration)Global styles in `src/styles/global.css`Utility function `cn()` in `src/lib/utils.ts` for className merging**Component Flexibility**: Build components to support both The Looker and future Daily Beast brandingDevelopment Best Practices
1. **Ask before implementing** - Always clarify requirements and approach before making big architectural decisions
2. **Error handling** - Handle missing data gracefully - all fields should have defaults
3. **TypeScript everywhere** - Use TypeScript for type safety throughout
4. **Test thoroughly** - Verify changes work correctly before committing
5. **Maintain documentation**:
- Keep an AI decision log of important choices
- Update `TASKS.md` constantly with current state and priorities
- Document any non-obvious implementation details
6. **Reusability focus** - Components will eventually power the full Daily Beast site
7. **Use existing components** - Only use out-of-the-box components without explicit approval for custom builds
Sample Data Reference
The `documentation/` folder contains sample JSON files for development:
`sample-article.json` - Standard article structure`sample-collection.json` - Homepage collection structure`article-with-all-elements.json` - Complete article with every block type`apis.json` & `middleware-api.json` - API documentationImportant Notes
The project manager agent should maintain a log of AI decisionsAlways update `TASKS.md` with current progress and next stepsTest all changes thoroughly before committingAsk questions when uncertain about requirements or implementation approachComponents must be flexible enough to support future Daily Beast branding migration