From 0d42a77258776cb190ceb13568d5851e5cdb8c09 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 6 Oct 2026 11:44:45 -0400 Subject: [PATCH] docs: match READMEs to the build, release and wizard flow Checked against origin/main code. Docs only. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 27 ++--- CONTRIBUTING.md | 22 ++-- README.md | 64 ++++++++---- example-apps/android/README.md | 134 ++++++++++++------------- example-apps/angular/README.md | 15 +-- example-apps/expo/README.md | 20 ++-- example-apps/fastapi/README.md | 2 +- example-apps/flask/README.md | 2 +- example-apps/javascript-node/README.md | 2 +- example-apps/javascript-web/README.md | 2 +- example-apps/laravel/README.md | 2 +- example-apps/php/README.md | 2 +- example-apps/python/README.md | 2 +- example-apps/ruby/README.md | 2 +- 14 files changed, 163 insertions(+), 135 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 951c04ba4..6b4fa9c90 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,12 +38,12 @@ promotion criterion live in cli: role: command # command | skill | internal parentCommand: audit # optional — nests this command under another - command: events # the user-typed word; required when role is command + command: events # the user-typed word, defaults to the variant id ``` The parser is `parseCliBlock` in `scripts/lib/skill-generator.js`. It enforces: -- `role` is one of `command`, `skill`, `internal` (default: `skill` if no `cli:` block is set at all) +- `role` is required and is one of `command`, `skill`, `internal`. A skill with no `cli:` block gets no `cliEntries` entry. - `command` and `parentCommand` are kebab-case, 2–20 characters - Neither field is a yargs reserved word (`help`, `version`, `completion`) or a wizard internal flag (`playground`, `benchmark`, `yara-report`, `local-mcp`, `ci`, `skill`) - `default` (optional, boolean) marks the leaf `wizard ` runs by default (and pre-highlights it in the picker once a family has several) @@ -58,8 +58,8 @@ lands. See [CONTRIBUTING.md § Flat vs. family](CONTRIBUTING.md#flat-vs-family-- ### When you're about to change a `cli:` block 1. Read [CONTRIBUTING.md § Promotion criterion for `role: command`](CONTRIBUTING.md#promotion-criterion-for-role-command). -2. Run `npm test` — the parser's suite (`scripts/lib/tests/cli-block.test.js`) covers every naming-convention case. -3. Run `npm run build` — confirm the entry appears (or disappears) under `cliEntries` in `dist/skills/skill-menu.json` with the values you expect. +2. Run `pnpm test` — the parser's suite (`scripts/lib/tests/cli-block.test.js`) covers every naming-convention case. +3. Run `pnpm run build` — confirm the entry appears (or disappears) under `cliEntries` in `dist/skills/skill-menu.json` with the values you expect. 4. The wizard resolves new entries at runtime, so no wizard release is required unless the change needs wizard-side hooks (custom outro, content blocks, abort cases). ## Wizard CLI command mapping (old → new) @@ -80,8 +80,9 @@ longer exist — only some keep an alias. | Subcommand | Backing skill | |---|---| -| `wizard audit events` | `audit-events` (default leaf) | -| `wizard audit all` | `audit` | +| `wizard audit events` | `audit-events` | +| `wizard audit all` | `audit` (default leaf) | +| `wizard audit attribution` | `audit-attribution` | | `wizard audit autocapture` | `audit-autocapture` | | `wizard audit feature-flags` | `audit-feature-flags` | | `wizard audit identify` | `audit-identify` | @@ -105,19 +106,19 @@ caller instead. ## Commands ```bash -npm install # Install dependencies -npm test # vitest run (parsers, expander, plugins, cli block) -npm run build # Full build: emits dist/skills/.zip + manifests -npm run dev # Partial-rebuild dev server with watch +pnpm install # Install dependencies +pnpm test # vitest run (parsers, expander, plugins, cli block) +pnpm run build # Full build: emits dist/skills/.zip + manifests +pnpm run dev # Partial-rebuild dev server with watch ``` ## Repository conventions - Skill content lives in markdown, never in JS/TS. The build pipeline reads YAML configs and stitches markdown together; it doesn't generate prose. - The `cli:` block is the **single source of truth** for the wizard's command surface for any skill. Don't duplicate command names in the wizard repo; they're derived from the manifest. -- `additionalProperties: false` is set on the JSON Schema — adding a new field to the manifest shape is a coordinated change (bump the schema, bump consumer types in the wizard). See [PostHog/wizard CONTRIBUTING.md](https://github.com/PostHog/wizard/blob/main/CONTRIBUTING.md) for the wizard-side contract. +- Changing the `skill-menu.json` shape is a coordinated change. Update the consumer types in the wizard too. See [PostHog/wizard AGENTS.md](https://github.com/PostHog/wizard/blob/main/AGENTS.md) for the wizard-side contract. ## Companion projects -- **[wizard](https://github.com/PostHog/wizard)** — the CLI that consumes the manifest at build time and turns each `role: command` entry into a registered command. -- **[warlock](https://github.com/PostHog/warlock)** — the security scanner used by the wizard. Unrelated to skill content but lives alongside in the same engineering scope. +- **[wizard](https://github.com/PostHog/wizard)** — the CLI that fetches `skill-menu.json` at runtime and turns each `role: command` entry into a registered command. +- **[warlock](https://github.com/PostHog/warlock)** — PostHog's security scanner for agentic flows. context-mill depends on `@posthog/warlock`, and CI scans the built skill bundles with it (`scripts/scan-warlock.js`). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f42476e5d..05ea68672 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,7 @@ description: Audit captured events cli: role: command # command | skill | internal parentCommand: audit # the command this skill nests under (optional) - command: events # the user-typed word; required when role is command + command: events # the user-typed word, defaults to the variant id default: true # optional — the leaf `wizard ` runs by default ``` @@ -32,10 +32,11 @@ Three values for `role`: |---|---| | `command` | Registered as `wizard ` (or `wizard ` if no parent). The user-facing CLI. | | `skill` | Reachable only via `wizard skill `. The full discoverable set. | -| `internal` | Hidden everywhere. Only reachable via `wizard --skill=` (a dev escape hatch). Useful for in-progress skills that aren't ready to expose. | +| `internal` | Hidden from `wizard skill list`. Still runs via `wizard skill `. Useful for in-progress skills that aren't ready to expose. | -Skills with **no** `cli:` block default to the `skill` role — they're -discoverable via `wizard skill list` but don't get a top-level command. +Skills with **no** `cli:` block get no entry in `cliEntries`. They never +appear in `wizard skill list` and don't get a top-level command. They still +run via `wizard skill `. The same skill can be either surface: `audit-events` sets `role: command` so it's `wizard audit events`; a `role: skill` skill is only `wizard skill `. One @@ -100,7 +101,7 @@ Use the **full PostHog product name** with hyphens, not abbreviations. | Session replay audit | `wizard audit session-replay` | `wizard audit replay` | | Revenue analytics | `wizard revenue-analytics` | `wizard revenue` | | Web analytics | `wizard web-analytics` | `wizard web` | -| AI Observability | `wizard llm-analytics` | `wizard llms` | +| AI Observability | `wizard ai-observability` | `wizard llms` | The kebab-case / length / reserved-word checks in `parseCliBlock` enforce the mechanics; this rule is the naming taste layer on top of @@ -194,8 +195,11 @@ The base path is the same regardless of the skill's CLI role: 3. Add a `description.md` template and any `references/*.md` files. 4. If the skill should be a wizard command, add a `cli:` block per the schema above. -5. Run `npm test && npm run build`. The build emits the new skill into - `dist/skills/.zip` and lists it in the manifest. +5. Run `pnpm test && pnpm run build`. The build emits one ZIP per variant, + `dist/skills/-.zip`, and lists it in the manifest. + An `id: all` variant emits `dist/skills/.zip` instead. A + bundled group (`packaging: bundle`) emits one `dist/skills/.json` + with every variant inside, and those variants get no manifest entry. ## Adding a new command @@ -204,7 +208,7 @@ When you've decided your skill meets the `role: command` criterion: 1. Add the `cli:` block to the skill's `config.yaml` with `role: command`, the right `parentCommand` (if it nests under an existing family), and `command`. -2. Confirm `npm run build` emits the entry under `cliEntries` inside +2. Confirm `pnpm run build` emits the entry under `cliEntries` inside `dist/skills/skill-menu.json` with the right `parentCommand` / `command` values. The wizard picks it up on its next invocation (no wizard release needed). @@ -234,7 +238,7 @@ manifest is published before the wizard tries to consume it. (`parseCliBlock`, `expandSkillGroups`, JSDoc typedef for the `cli:` block) - CLI entries emit: `scripts/lib/build-phases.js` (`generateCliEntries`) - Tests for the cli block parser: `scripts/lib/tests/cli-block.test.js` -- The wizard's side of the contract: [PostHog/wizard CONTRIBUTING.md](https://github.com/PostHog/wizard/blob/main/CONTRIBUTING.md) +- The wizard's side of the contract: [PostHog/wizard AGENTS.md](https://github.com/PostHog/wizard/blob/main/AGENTS.md) Questions: drop a note in [#team-docs-and-wizard](https://posthog.slack.com/archives/C09GTQY5RLZ) or diff --git a/README.md b/README.md index 53a2e6c96..520f8de14 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ We'd love your pull request! The context mill gathers up-to-date content from multiple sources, packaging PostHog developer docs, prompts, and working example code into a versioned manifest which can be shipped anywhere as a zip file. -The [PostHog MCP server](https://github.com/PostHog/posthog/tree/master/services/mcp) currently fetches the examples repo manifest and exposes it to any MCP-compatible client as resources and slash commands. This is what currently powers the PostHog [wizard](https://github.com/PostHog/wizard). +The [PostHog MCP server](https://github.com/PostHog/posthog/tree/master/services/mcp) currently fetches the examples repo manifest and exposes it to any MCP-compatible client as resources and slash commands. The PostHog [wizard](https://github.com/PostHog/wizard) fetches `skill-menu.json` and skill ZIPs from the context mill's GitHub releases itself. It falls back to the AWS mirror at `context-mill.posthog.com` when GitHub fails. ## Context engine @@ -37,38 +37,54 @@ These are more like model airplanes. They're dramatically simplified to make it But the leanness makes these useful for agent-driven development. Use these as context to help your agent make better integration decisions about PostHog. ``` -examples/ -├── basics/ -│ ├── next-app-router/ # Next.js 15 with App Router -│ ├── next-pages-router/ # Next.js 15 with Pages Router -│ ├── react-react-router/ # React with React Router +context-mill/ +├── context/ # Skill sources, agent prompts, and build config +├── example-apps/ # One flat folder per example app +│ ├── next-app-router/ # Next.js with App Router +│ ├── next-pages-router/ # Next.js with Pages Router +│ ├── react-react-router-7-framework/ # React with React Router 7 (framework mode) │ ├── react-tanstack-router-file-based/ # React with TanStack Router (file-based) │ ├── react-tanstack-router-code-based/ # React with TanStack Router (code-based) │ ├── tanstack-start/ # TanStack Start -│ └── django/ # Django -├── mcp-commands/ # MCP command prompts (`/command` in agents) +│ ├── django/ # Django +│ └── ... # Every other example app └── scripts/ # Build scripts ``` ## Build outputs -Run `npm run build` to generate the release artifacts: +Run `pnpm run build` to generate the release artifacts: | Output | Description | |--------|-------------| | `dist/skills/.zip` | Per-skill bundles (SKILL.md + references + shared docs) | | `dist/skills/manifest.json` | Versioned manifest of every bundled skill and its download URL | | `dist/skills/skill-menu.json` | Category groupings and `cliEntries` — the wizard's command lookup table | +| `dist/skills/.json` | One file per bundled group (`packaging: bundle`), holding every variant | +| `dist/skills-mcp-resources.zip` | `manifest.json` plus every skill ZIP and bundle JSON in one archive | -Releases are cut as GitHub releases. Consumers (the wizard, the MCP server, -anything else) fetch `manifest.json` / `skill-menu.json` from the latest -release and download the per-skill ZIPs on demand. +Releases are cut as GitHub releases and mirrored to `context-mill.posthog.com`. +Each release carries these assets: + +- `skills-mcp-resources.zip`, which holds `manifest.json`, the skill ZIPs, and the bundle JSONs +- one ZIP per skill +- `skill-menu.json` +- one `.json` per bundled group +- `agent-menu.json` and the `agents-*.md` orchestrator prompts +- any reference docs (`*.md`) in `dist/skills/` + +`manifest.json` is not a standalone release asset. It only ships inside +`skills-mcp-resources.zip`. The wizard fetches `skill-menu.json` from the +latest release and downloads skill ZIPs or bundle JSONs on demand. ### Manifest structure The manifest describes the built skills — one resource per skill, with `id`, `name`, `description`, `tags`, `uri`, and a `downloadUrl` pointing at the -GitHub release asset. Each bundled skill contains a `SKILL.md`, `references/` +GitHub release asset. Bundled variants (`packaging: bundle`) ship inside their +group's JSON, so they have no manifest entry. The manifest also has one +resource per doc in `context/docs.yaml`, with the doc's Markdown inline +instead of a `downloadUrl`. Each bundled skill contains a `SKILL.md`, `references/` step files, and any shared docs pulled from posthog.com at build time. ### Adding a new skill @@ -102,8 +118,9 @@ surface. If you (or your agent) knew an older command, here's where it went: | Subcommand | Backing skill | |---|---| -| `wizard audit events` | `audit-events` (the default leaf) | -| `wizard audit all` | `audit` | +| `wizard audit events` | `audit-events` | +| `wizard audit all` | `audit` (the default leaf) | +| `wizard audit attribution` | `audit-attribution` | | `wizard audit autocapture` | `audit-autocapture` | | `wizard audit feature-flags` | `audit-feature-flags` | | `wizard audit identify` | `audit-identify` | @@ -130,19 +147,24 @@ review to their owning team instead. | Path | Owning team | |---|---| | `*` (everything else, including all other skills) | `@PostHog/team-wizard-docs` | -| `context/skills/integration/` | `@PostHog/team-wizard-docs` | | `context/skills/error-tracking-upload-source-maps/` | `@PostHog/team-error-tracking` | | `context/skills/error-tracking-link-releases/` | `@PostHog/team-error-tracking` | -| `context/skills/mcp-analytics/` | `@PostHog/team-mcp-analytics` | -| `context/skills/revenue-analytics/` | `@PostHog/team-web-analytics` | | `context/skills/self-driving/` | `@PostHog/team-self-driving` | | `context/skills/data-warehouse-source/` | `@PostHog/team-warehouse-sources` | +| `context/skills/mcp-analytics/` | `@PostHog/team-mcp-analytics` | +| `context/skills/metrics/` | `@PostHog/apm` | +| `context/agents/metrics/` | `@PostHog/apm` | +| `context/skills/revenue-analytics/` | `@PostHog/team-web-analytics` | | `context/skills/web-analytics/` | `@PostHog/team-web-analytics` | +| `context/skills/integration/` | `@PostHog/team-wizard-docs` | +| `context/skills/replay-vision*/` | `@PostHog/team-replay` | +| `context/skills/ai-observability/` | `@PostHog/team-ai-observability` | +| `context/skills/llm-analytics/` | `@PostHog/team-ai-observability` | Ownership is by directory. Skills not listed above (`audit`, `audit-*`, -`cost-cutting`, `creating-product-tours`, `error-tracking`, `events-audit`, -`feature-flags`, `llm-analytics`, `logs`, `migrate`, `omnibus`, -`posthog-best-practices`, `quack`, `tools-and-features`) fall through the +`creating-product-tours`, `error-tracking`, `events-audit`, `feature-flags`, +`integration-v2`, `logs`, `migrate`, `omnibus`, `posthog-best-practices`, +`quack`, `tools-and-features`, `tracing`) fall through the default and are owned by `team-wizard-docs`. Today CODEOWNERS only auto-requests review — approval is not a merge gate. diff --git a/example-apps/android/README.md b/example-apps/android/README.md index 3a978aca7..f69b810da 100644 --- a/example-apps/android/README.md +++ b/example-apps/android/README.md @@ -32,13 +32,13 @@ posthog.apiKey=your_posthog_project_token posthog.host=https://us.i.posthog.com ``` -Alternatively, you can configure PostHog in your `build.gradle` file: +Alternatively, you can configure PostHog in your `app/build.gradle.kts` file: -```gradle +```kotlin android { defaultConfig { - buildConfigField "String", "POSTHOG_PROJECT_TOKEN", "\"your_posthog_project_token\"" - buildConfigField "String", "POSTHOG_HOST", "\"https://us.i.posthog.com\"" + buildConfigField("String", "POSTHOG_PROJECT_TOKEN", "\"your_posthog_project_token\"") + buildConfigField("String", "POSTHOG_HOST", "\"https://us.i.posthog.com\"") } } ``` @@ -58,28 +58,37 @@ Get your PostHog project token from your [PostHog project settings](https://app. │ ├── src/ │ │ ├── main/ │ │ │ ├── java/com/example/posthog/ -│ │ │ │ ├── BurritoApplication.kt # Application class with PostHog initialization -│ │ │ │ ├── MainActivity.kt # Main activity +│ │ │ │ ├── BurritoApp.kt # Application class with PostHog initialization +│ │ │ │ ├── MainActivity.kt # Main activity +│ │ │ │ ├── data/ +│ │ │ │ │ ├── User.kt # User model +│ │ │ │ │ └── UserRepository.kt # User storage in SharedPreferences +│ │ │ │ ├── navigation/ +│ │ │ │ │ └── NavGraph.kt # Navigation routes │ │ │ │ ├── ui/ │ │ │ │ │ ├── screens/ -│ │ │ │ │ │ ├── LoginScreen.kt # Login screen with user identification +│ │ │ │ │ │ ├── HomeScreen.kt # Home screen with login form │ │ │ │ │ │ ├── BurritoScreen.kt # Demo feature screen with event tracking │ │ │ │ │ │ └── ProfileScreen.kt # User profile with error tracking demo -│ │ │ │ │ └── components/ # Reusable UI components -│ │ │ │ └── utils/ -│ │ │ │ └── PostHogHelper.kt # PostHog utility functions +│ │ │ │ │ ├── components/ # Reusable UI components +│ │ │ │ │ └── theme/ # Compose theme +│ │ │ │ └── viewmodel/ +│ │ │ │ └── AuthViewModel.kt # Login, logout, and user identification │ │ │ ├── res/ # Resources (layouts, strings, etc.) │ │ │ └── AndroidManifest.xml # App manifest -│ │ └── test/ # Unit tests -│ └── build.gradle # App-level Gradle configuration -├── build.gradle # Project-level Gradle configuration -├── settings.gradle # Gradle settings -└── local.properties # Local configuration (gitignored) +│ │ ├── test/ # Unit tests +│ │ └── androidTest/ # Instrumented tests +│ └── build.gradle.kts # App-level Gradle configuration +├── gradle/ +│ └── libs.versions.toml # Dependency versions +├── build.gradle.kts # Project-level Gradle configuration +├── settings.gradle.kts # Gradle settings +└── local.properties.example # Template for local.properties (gitignored) ``` ## Key Integration Points -### Application Initialization (BurritoApplication.kt) +### Application Initialization (BurritoApp.kt) PostHog is initialized in the `Application` class to ensure it's available throughout the app lifecycle: @@ -87,56 +96,42 @@ PostHog is initialized in the `Application` class to ensure it's available throu class BurritoApplication : Application() { override fun onCreate() { super.onCreate() - - val posthogConfig = PostHogConfig( + + // Initialize PostHog early in Application lifecycle + val config = PostHogAndroidConfig( apiKey = BuildConfig.POSTHOG_PROJECT_TOKEN, - host = BuildConfig.POSTHOG_HOST + host = BuildConfig.POSTHOG_HOST, ).apply { - // Enable session replay - sessionReplay = true - - // Enable automatic exception capture - captureApplicationLifecycleEvents = true - captureDeepLinks = true - captureScreenViews = true + debug = true + errorTrackingConfig.autoCapture = true } - - PostHog.setup(this, posthogConfig) + + PostHogAndroid.setup(this, config) } } ``` **Key Points:** - PostHog is initialized in `onCreate()` to ensure it's initialized as early as possible -- Configuration is loaded from `BuildConfig` (set in `build.gradle`) -- Session replay, lifecycle events, and screen views are enabled +- Configuration is loaded from `BuildConfig` (set in `app/build.gradle.kts`) +- Debug logging and automatic error capture are enabled - The Application class must be registered in `AndroidManifest.xml` -### User Identification (LoginScreen.kt) +### User Identification (AuthViewModel.kt) Users are identified when they log in: ```kotlin -val posthog = PostHog.getInstance() - -fun handleLogin(username: String, password: String) { - // Authenticate user - val success = authenticateUser(username, password) - - if (success) { - // Identify the user once on login/sign up - posthog.identify( - distinctId = username, - properties = mapOf( - "username" to username, - "login_method" to "password" - ) - ) - - // Capture login event - posthog.capture("user_logged_in", mapOf( - "username" to username - )) +fun login(username: String) { + viewModelScope.launch { + val existingUser = repository.getUser(username) + val user = existingUser ?: User(username = username, burritoConsiderations = 0) + repository.saveUser(user) + _currentUser.value = user + _isAuthenticated.value = true + + PostHog.identify(username) + PostHog.capture(event = "user_logged_in") } } ``` @@ -253,37 +248,42 @@ The instance is available throughout your application after initialization. ## Gradle Configuration -### App-level build.gradle +### App-level build.gradle.kts -```gradle +```kotlin android { defaultConfig { // PostHog configuration - buildConfigField "String", "POSTHOG_PROJECT_TOKEN", "\"${project.findProperty("posthog.apiKey") ?: ""}\"" - buildConfigField "String", "POSTHOG_HOST", "\"${project.findProperty("posthog.host") ?: "https://us.i.posthog.com"}\"" + buildConfigField( + "String", + "POSTHOG_PROJECT_TOKEN", + "\"${localProperties.getProperty("posthog.apiKey", "")}\"" + ) + buildConfigField( + "String", + "POSTHOG_HOST", + "\"${localProperties.getProperty("posthog.host", "https://us.i.posthog.com")}\"" + ) } } dependencies { - // PostHog Android SDK - implementation 'com.posthog:posthog-android:3.+' - + // PostHog Android SDK, version set in gradle/libs.versions.toml + implementation(libs.posthog.android) + // Other dependencies... } ``` ### Reading from local.properties -The `local.properties` file is automatically read by Gradle: +`app/build.gradle.kts` loads `local.properties` when the file exists. Copy `local.properties.example` to `local.properties` to create it: -```gradle -def localProperties = new Properties() -localProperties.load(new FileInputStream(rootProject.file("local.properties"))) - -android { - defaultConfig { - buildConfigField "String", "POSTHOG_PROJECT_TOKEN", "\"${localProperties.getProperty("posthog.apiKey", "")}\"" - buildConfigField "String", "POSTHOG_HOST", "\"${localProperties.getProperty("posthog.host", "https://us.i.posthog.com")}\"" +```kotlin +val localProperties = Properties().apply { + val localPropertiesFile = rootProject.file("local.properties") + if (localPropertiesFile.exists()) { + load(localPropertiesFile.inputStream()) } } ``` diff --git a/example-apps/angular/README.md b/example-apps/angular/README.md index 0b924816c..e2143291c 100644 --- a/example-apps/angular/README.md +++ b/example-apps/angular/README.md @@ -24,8 +24,8 @@ pnpm install Create a `.env` file in the root directory: ```bash -VITE_POSTHOG_PROJECT_TOKEN=your_posthog_project_token -VITE_POSTHOG_HOST=https://us.posthog.com +NG_APP_POSTHOG_PROJECT_TOKEN=your_posthog_project_token +NG_APP_POSTHOG_HOST=https://us.posthog.com ``` Get your PostHog project token from your [PostHog project settings](https://app.posthog.com/project/settings). @@ -59,6 +59,7 @@ src/ │ └── app.config.ts # App configuration ├── environments/ │ ├── environment.ts # Dev environment config +│ ├── environment.prod.ts │ └── environment.production.ts └── main.ts # App entry point ``` @@ -158,15 +159,15 @@ This example uses Angular 21 with modern features: 3. **SSR support**: Uses `isPlatformBrowser()` checks for SSR safety 4. **Dependency injection**: PostHog wrapped in an injectable service 5. **Proxy configuration**: Uses `proxy.conf.json` for PostHog API calls -6. **Environment files**: Generated from `.env` at build time via prebuild script +6. **Environment files**: Read `.env` at build time via `@ngx-env/builder` ## Environment variable handling -Angular CLI doesn't natively support `.env` files. This project uses a prebuild script: +Angular CLI doesn't natively support `.env` files. This project uses `@ngx-env/builder`: -1. `scripts/generate-env.js` reads `.env` and generates `environment.generated.ts` -2. The script runs automatically before `pnpm start` and `pnpm build` -3. Environment files import from the generated file +1. `angular.json` runs the `@ngx-env/builder` builders for `serve`, `build`, and `test` +2. The builder loads `.env` and exposes `NG_APP_*` variables on `import.meta.env` +3. Environment files read `import.meta.env['NG_APP_POSTHOG_PROJECT_TOKEN']` and `import.meta.env['NG_APP_POSTHOG_HOST']` ## Learn more diff --git a/example-apps/expo/README.md b/example-apps/expo/README.md index fbb47274d..ce9132020 100644 --- a/example-apps/expo/README.md +++ b/example-apps/expo/README.md @@ -16,7 +16,7 @@ A React Native Expo app demonstrating PostHog product analytics integration with ## Project Structure ``` -basics/expo/ +example-apps/expo/ ├── app/ # Expo Router screens (file-based routing) │ ├── _layout.tsx # Root layout with PostHogProvider + AuthProvider │ ├── index.tsx # Home screen (login/welcome) @@ -31,7 +31,7 @@ basics/expo/ │ │ └── storage.ts # AsyncStorage wrapper │ └── styles/ │ └── theme.ts # Shared style constants -├── app.json # Expo configuration +├── app.config.js # Expo configuration ├── babel.config.js # Babel config with React Compiler ├── eslint.config.js # ESLint flat config ├── package.json # Dependencies @@ -68,7 +68,7 @@ Then run `source ~/.zshrc` to apply. 1. Install dependencies: ```bash - cd basics/expo + cd example-apps/expo npm install ``` @@ -100,7 +100,7 @@ npx expo run:android ### Configuration -PostHog is configured in `src/config/posthog.ts` using environment variables from `app.json`: +PostHog is configured in `src/config/posthog.ts` using environment variables passed through `app.config.js`: ```typescript import Constants from 'expo-constants' @@ -172,13 +172,13 @@ export function useAuth() { ### New Architecture -Enabled in `app.json` for better performance: +Enabled in `app.config.js` for better performance: -```json -{ - "expo": { - "newArchEnabled": true - } +```js +export default { + expo: { + newArchEnabled: true, + }, } ``` diff --git a/example-apps/fastapi/README.md b/example-apps/fastapi/README.md index 2879d3bd5..a2e60f9f1 100644 --- a/example-apps/fastapi/README.md +++ b/example-apps/fastapi/README.md @@ -108,7 +108,7 @@ The `/api/test-error` endpoint demonstrates manual exception capture. Use `?capt ## Project Structure ``` -basics/fastapi/ +example-apps/fastapi/ ├── app/ │ ├── __init__.py # Package marker │ ├── config.py # Pydantic Settings configuration diff --git a/example-apps/flask/README.md b/example-apps/flask/README.md index 74f7074df..df9c5712c 100644 --- a/example-apps/flask/README.md +++ b/example-apps/flask/README.md @@ -108,7 +108,7 @@ The `/api/test-error` endpoint demonstrates manual exception capture. Use `?capt ## Project Structure ``` -basics/flask/ +example-apps/flask/ ├── app/ │ ├── __init__.py # Application factory │ ├── config.py # Configuration classes diff --git a/example-apps/javascript-node/README.md b/example-apps/javascript-node/README.md index a033d01bc..e26f04a20 100644 --- a/example-apps/javascript-node/README.md +++ b/example-apps/javascript-node/README.md @@ -82,7 +82,7 @@ The app tracks these events in PostHog: ## Code structure ``` -basics/javascript-node/ +example-apps/javascript-node/ ├── todo.js # Express server with PostHog tracking ├── package.json # Node.js dependencies ├── .env.example # Environment variable template diff --git a/example-apps/javascript-web/README.md b/example-apps/javascript-web/README.md index 61e036305..6ad07414f 100644 --- a/example-apps/javascript-web/README.md +++ b/example-apps/javascript-web/README.md @@ -59,7 +59,7 @@ The app tracks these custom events in PostHog (in addition to autocaptured click ## Code Structure ``` -basics/javascript/ +example-apps/javascript-web/ ├── index.html # Entry HTML page ├── package.json # Dependencies (posthog-js, vite) ├── vite.config.js # Vite configuration diff --git a/example-apps/laravel/README.md b/example-apps/laravel/README.md index 42a28e32e..d6cee9393 100644 --- a/example-apps/laravel/README.md +++ b/example-apps/laravel/README.md @@ -186,7 +186,7 @@ The `/api/test-error` endpoint demonstrates manual exception capture. Use `?capt ## Project Structure ``` -basics/laravel/ +example-apps/laravel/ ├── app/ │ ├── Http/ │ │ ├── Controllers/ diff --git a/example-apps/php/README.md b/example-apps/php/README.md index c77109335..c21195d1a 100644 --- a/example-apps/php/README.md +++ b/example-apps/php/README.md @@ -71,7 +71,7 @@ The app tracks these events in PostHog: ## Code Structure ``` -basics/php/ +example-apps/php/ ├── todo.php # Main CLI application ├── composer.json # PHP dependencies ├── .env.example # Environment variable template diff --git a/example-apps/python/README.md b/example-apps/python/README.md index 186093bb1..f82e6201b 100644 --- a/example-apps/python/README.md +++ b/example-apps/python/README.md @@ -76,7 +76,7 @@ The app tracks these events in PostHog: ## Code Structure ``` -basics/python/ +example-apps/python/ ├── todo.py # Main CLI application ├── requirements.txt # Python dependencies ├── .env.example # Environment variable template diff --git a/example-apps/ruby/README.md b/example-apps/ruby/README.md index cc21e893d..67e31dfbb 100644 --- a/example-apps/ruby/README.md +++ b/example-apps/ruby/README.md @@ -74,7 +74,7 @@ The app tracks these events in PostHog: ## Code Structure ``` -basics/ruby/ +example-apps/ruby/ ├── todo.rb # Main CLI application ├── Gemfile # Ruby dependencies ├── .env.example # Environment variable template