npm - quiver-cli - Versions diffs - 0.1.0 - Mend

quiver-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (281) hide show

package/template/.agents/skills/integrations/posthog/references/error-tracking-nextjs.md ADDED Viewed

@@ -0,0 +1,490 @@
+# Next.js error tracking installation - Docs
+1.  1
+    ## Install the package
+    Required
+    Install the PostHog JavaScript library using your package manager:
+    PostHog AI
+    ### npm
+    ```bash
+    npm install posthog-js
+    ```
+    ### yarn
+    ```bash
+    yarn add posthog-js
+    ```
+    ### pnpm
+    ```bash
+    pnpm add posthog-js
+    ```
+2.  2
+    ## Add environment variables
+    Required
+    Add your PostHog project token and host to your `.env.local` file and to your hosting provider (e.g. Vercel, Netlify). These values need to start with `NEXT_PUBLIC_` to be accessible on the client-side.
+    .env.local
+    PostHog AI
+    ```bash
+    NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=<ph_project_token>
+    NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
+    ```
+3.  3
+    ## Initialize PostHog
+    Required
+    Choose the integration method based on your Next.js version and router type.
+    ## Next.js 15.3+
+    If you're using Next.js 15.3+, you can use `instrumentation-client.ts` for a lightweight, fast integration:
+    instrumentation-client.ts
+    PostHog AI
+    ```typescript
+    import posthog from 'posthog-js'
+    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN!, {
+        api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+        defaults: '2026-01-30'
+    })
+    ```
+    ## App router
+    For the App router, create a `providers.tsx` file in your `app` folder. The `posthog-js` library needs to be initialized on the client-side using the `'use client'` directive:
+    app/providers.tsx
+    PostHog AI
+    ```typescript
+    'use client'
+    import { usePathname, useSearchParams } from "next/navigation"
+    import { useEffect } from "react"
+    import posthog from 'posthog-js'
+    import { PostHogProvider as PHProvider } from 'posthog-js/react'
+    export function PostHogProvider({ children }: { children: React.ReactNode }) {
+      useEffect(() => {
+        posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN as string, {
+          api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+          defaults: '2026-01-30'
+        })
+      }, [])
+      return (
+        <PHProvider client={posthog}>
+          {children}
+        </PHProvider>
+      )
+    }
+    ```
+    Then import the `PostHogProvider` component in your `app/layout.tsx` and wrap your app with it:
+    app/layout.tsx
+    PostHog AI
+    ```typescript
+    import './globals.css'
+    import { PostHogProvider } from './providers'
+    export default function RootLayout({ children }: { children: React.ReactNode }) {
+      return (
+        <html lang="en">
+          <body>
+            <PostHogProvider>
+              {children}
+            </PostHogProvider>
+          </body>
+        </html>
+      )
+    }
+    ```
+    ## Pages router
+    For the Pages router, integrate PostHog at the root of your app in `pages/_app.tsx`:
+    pages/\_app.tsx
+    PostHog AI
+    ```typescript
+    import { useEffect } from 'react'
+    import { Router } from 'next/router'
+    import posthog from 'posthog-js'
+    import { PostHogProvider } from 'posthog-js/react'
+    import type { AppProps } from 'next/app'
+    export default function App({ Component, pageProps }: AppProps) {
+      useEffect(() => {
+        posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN as string, {
+          api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+          defaults: '2026-01-30',
+          loaded: (posthog) => {
+            if (process.env.NODE_ENV === 'development') posthog.debug()
+          }
+        })
+      }, [])
+      return (
+        <PostHogProvider client={posthog}>
+          <Component {...pageProps} />
+        </PostHogProvider>
+      )
+    }
+    ```
+    **Defaults option**
+    The `defaults` option automatically configures PostHog with recommended settings for new projects. See [SDK defaults](/docs/libraries/js.md#sdk-defaults) for details.
+4.  4
+    ## Accessing PostHog on the client
+    Recommended
+    ## Next.js 15.3+
+    Once initialized in `instrumentation-client.ts`, import `posthog` from `posthog-js` anywhere and call the methods you need:
+    app/checkout/page.tsx
+    PostHog AI
+    ```typescript
+    'use client'
+    import posthog from 'posthog-js'
+    export default function CheckoutPage() {
+        function handlePurchase() {
+            posthog.capture('purchase_completed', { amount: 99 })
+        }
+        return <button onClick={handlePurchase}>Complete purchase</button>
+    }
+    ```
+    ## App/Pages router
+    Use the `usePostHog` hook to access PostHog in client components:
+    app/checkout/page.tsx
+    PostHog AI
+    ```typescript
+    'use client'
+    import { usePostHog } from 'posthog-js/react'
+    export default function CheckoutPage() {
+        const posthog = usePostHog()
+        function handlePurchase() {
+            posthog.capture('purchase_completed', { amount: 99 })
+        }
+        return <button onClick={handlePurchase}>Complete purchase</button>
+    }
+    ```
+5.  5
+    ## Capture client-side exceptions
+    Required
+    PostHog can automatically capture unhandled exceptions in your Next.js app using the JavaScript Web SDK.
+    You can enable exception autocapture for the JavaScript Web SDK in the **Error tracking** section of [your project settings](https://us.posthog.com/settings/project-error-tracking#exception-autocapture).
+    It is also possible to manually capture exceptions using the `captureException` method:
+    JavaScript
+    PostHog AI
+    ```javascript
+    posthog.captureException(error, additionalProperties)
+    ```
+    Manual capture is very useful if you already use error boundaries to handle errors in your app:
+    ## App router
+    Next.js uses [error boundaries](https://nextjs.org/docs/app/building-your-application/routing/error-handling#using-error-boundaries) to handle uncaught exceptions by rendering a fallback UI instead of the crashing components. To set one up, create a `error.tsx` file in any of your route directories. This triggers when there is an error rendering your component and should look like this:
+    error.tsx
+    PostHog AI
+    ```typescript
+    "use client"
+    import posthog from "posthog-js"
+    import { useEffect } from "react"
+    export default function Error({
+      error,
+      reset,
+    }: {
+      error: Error & { digest?: string }
+      reset: () => void
+    }) {
+      useEffect(() => {
+        posthog.captureException(error)
+      }, [error])
+      return (
+        ...
+      )
+    }
+    ```
+    You can also create a [Global Error component](https://nextjs.org/docs/app/building-your-application/routing/error-handling#handling-global-errors) in your root layout to capture unhandled exceptions in your root layout.
+    app/global-error.tsx
+    PostHog AI
+    ```typescript
+    'use client'
+    import posthog from "posthog-js"
+    import NextError from "next/error"
+    import { useEffect } from "react"
+    export default function GlobalError({
+      error,
+      reset,
+    }: {
+      error: Error & { digest?: string }
+      reset: () => void
+    }) {
+      useEffect(() => {
+        posthog.captureException(error)
+      }, [error])
+      return (
+        // global-error must include html and body tags
+        <html>
+          <body>
+            {/* `NextError` is the default Next.js error page component */}
+            <NextError statusCode={0} />
+          </body>
+        </html>
+      )
+    }
+    ```
+    ## Pages router
+    For Pages Router, you can use React's [Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) to catch JavaScript errors anywhere in the component tree. Create a custom error boundary component and report errors to PostHog in the `componentDidCatch` method:
+    components/ErrorBoundary.tsx
+    PostHog AI
+    ```typescript
+    componentDidCatch(error, errorInfo) {
+      posthog.captureException(error)
+    }
+    ```
+    Then wrap your app or specific components with the error boundary:
+    pages/\_app.tsx
+    PostHog AI
+    ```typescript
+    import type { AppProps } from 'next/app'
+    import ErrorBoundary from '../components/ErrorBoundary'
+    export default function App({ Component, pageProps }: AppProps) {
+      return (
+        <ErrorBoundary>
+          <Component {...pageProps} />
+        </ErrorBoundary>
+      )
+    }
+    ```
+6.  6
+    ## Installing PostHog SDK for server-side
+    Required
+    Next.js enables you to both server-side render pages and add server-side functionality. To integrate PostHog into your Next.js app on the server-side, you can use the [Node SDK](/docs/libraries/node.md).
+    First, install the `posthog-node` library:
+    PostHog AI
+    ### npm
+    ```bash
+    npm install posthog-node --save
+    ```
+    ### yarn
+    ```bash
+    yarn add posthog-node
+    ```
+    ### pnpm
+    ```bash
+    pnpm add posthog-node
+    ```
+    ### bun
+    ```bash
+    bun add posthog-node
+    ```
+    For the backend, we can create a `lib/posthog-server.js` file. In it, initialize PostHog from `posthog-node` as a singleton with your project token and host from [your project settings](https://app.posthog.com/settings/project).
+    This looks like this:
+    lib/posthog-server.js
+    PostHog AI
+    ```javascript
+    import { PostHog } from 'posthog-node'
+    let posthogInstance = null
+    export function getPostHogServer() {
+      if (!posthogInstance) {
+        posthogInstance = new PostHog(
+          process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN,
+          {
+            host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
+            flushAt: 1,
+            flushInterval: 0,
+          }
+        )
+      }
+      return posthogInstance
+    }
+    ```
+    You can now use the `getPostHogServer` function to capture exceptions in server-side code.
+    JavaScript
+    PostHog AI
+    ```javascript
+    const posthog = getPostHogServer()
+    try {
+        throw new Error("This is a test exception for error tracking")
+    } catch (error) {
+        posthog.captureException(error, {
+            source: 'test',
+            user_id: 'test-user-123',
+        })
+    }
+    ```
+7.  ## Verify server-side exceptions
+    Recommended
+    You should also see events and exceptions in PostHog coming from your server-side code in the activity feed.
+    [Check for server events in PostHog](https://app.posthog.com/activity/explore)
+8.  7
+    ## Capturing server-side exceptions
+    Required
+    To capture errors that occur in your server-side code, you can set up an [`instrumentation.ts`](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) file at the root of your project. This provides a `onRequestError` hook that you can use to capture errors.
+    Importantly, you need to:
+    1.  Set up a `posthog-node` client in your server-side code. See our doc on [setting up Next.js server-side analytics](/docs/libraries/next-js.md#server-side-analytics.md) for more.
+    2.  Check the request is running in the `nodejs` runtime to ensure PostHog works. You can call `posthog.debug()` to get verbose logging.
+    3.  Get the `distinct_id` from the cookie to connect the error to a specific user.
+    This looks like this:
+    JavaScript
+    PostHog AI
+    ```javascript
+    // instrumentation.js
+    export function register() {
+      // No-op for initialization
+    }
+    export const onRequestError = async (err, request, context) => {
+      if (process.env.NEXT_RUNTIME === 'nodejs') {
+        const { getPostHogServer } = require('./lib/posthog-server')
+        const posthog = getPostHogServer()
+        let distinctId = null
+        if (request.headers.cookie) {
+          // Normalize multiple cookie arrays to string
+          const cookieString = Array.isArray(request.headers.cookie)
+            ? request.headers.cookie.join('; ')
+            : request.headers.cookie
+          const postHogCookieMatch = cookieString.match(/ph_phc_.*?_posthog=([^;]+)/)
+          if (postHogCookieMatch && postHogCookieMatch[1]) {
+            try {
+              const decodedCookie = decodeURIComponent(postHogCookieMatch[1])
+              const postHogData = JSON.parse(decodedCookie)
+              distinctId = postHogData.distinct_id
+            } catch (e) {
+              console.error('Error parsing PostHog cookie:', e)
+            }
+          }
+        }
+        await posthog.captureException(err, distinctId || undefined)
+      }
+    }
+    ```
+    You can find a full example of both this and client-side error tracking in our [Next.js error monitoring tutorial](/tutorials/nextjs-error-monitoring.md).
+9.  ## Verify error tracking
+    Recommended
+    *Confirm events are being sent to PostHog*
+    Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.
+    ![Activity feed with events](https://res.cloudinary.com/dmukukwp6/image/upload/SCR_20250729_ouxl_f788dd8cd2.png)![Activity feed with events](https://res.cloudinary.com/dmukukwp6/image/upload/SCR_20250729_owae_7c3490822c.png)
+    [Check for exceptions in PostHog](https://app.posthog.com/activity/explore)
+10.  8
+     ## Upload source maps
+     Required
+     Great, you're capturing exceptions! If you serve minified bundles, the next step is to upload source maps to generate accurate stack traces.
+     Let's continue to the next section.
+     [Upload source maps](/docs/error-tracking/upload-source-maps/nextjs.md)
+### Community questions
+Ask a question
+### Was this page useful?
+HelpfulCould be better

package/template/.agents/skills/integrations/posthog/references/error-tracking-source-maps.md ADDED Viewed

@@ -0,0 +1,45 @@
+# Upload source maps - Docs
+If you serve compiled or minified code, PostHog requires source maps to generate accurate stack traces.
+If your source maps are not publicly hosted, you will need to upload them during your build process to see unminified code in your stack traces.
+Choose your platform to view specific instructions.
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/js.svg)Web](/docs/error-tracking/upload-source-maps/web.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/frameworks/nextjs.svg)Next.js](/docs/error-tracking/upload-source-maps/nextjs.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/nodejs.svg)Node.js](/docs/error-tracking/upload-source-maps/node.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/react.svg)React](/docs/error-tracking/upload-source-maps/react.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/docs/integrate/frameworks/angular.svg)Angular](/docs/error-tracking/upload-source-maps/angular.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/frameworks/nuxt.svg)Nuxt](/docs/error-tracking/upload-source-maps/nuxt.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/react.svg)React Native](/docs/error-tracking/upload-source-maps/react-native.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/Android_robot_bec2fb7318.svg)Android](/docs/error-tracking/upload-mappings/android.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/flutter.svg)Flutter](/docs/error-tracking/upload-source-maps/flutter.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/ios.svg)iOS](/docs/error-tracking/upload-source-maps/ios.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/Rollup_js_c306a2fde3.svg)Rollup](/docs/error-tracking/upload-source-maps/rollup.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/webpack_3fc774b5a5.svg)Webpack](/docs/error-tracking/upload-source-maps/webpack.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/Vitejs_logo_98ffe5d5ee.svg)Vite](/docs/error-tracking/upload-source-maps/vite.md)
+-   [CLI](/docs/error-tracking/upload-source-maps/cli.md)
+-   [![](https://res.cloudinary.com/dmukukwp6/image/upload/github_mark_903e35d471.svg)GitHub Action](/docs/error-tracking/upload-source-maps/github-actions.md)
+### Community questions
+Ask a question
+### Was this page useful?
+HelpfulCould be better

package/template/.agents/skills/integrations/posthog/references/feature-flags-best-practices.md ADDED Viewed

@@ -0,0 +1,139 @@
+# Feature flag best practices - Docs
+## 1\. Use a reverse proxy
+Ad blockers have the potential to disable your feature flags, which can lead to bad experiences, such as users seeing the wrong version of your app, or missing a new feature rollout.
+To avoid this, deploy a reverse proxy, which enables you to make requests and send events to PostHog Cloud using your own domain.
+This means that requests are less likely to be intercepted by tracking blockers, and your feature flags are more likely to work as intended. You'll also capture more usage data.
+PostHog offers a free [managed reverse proxy](/docs/advanced/proxy/managed-reverse-proxy.md), or you can run your own. See our [reverse proxy docs](/docs/advanced/proxy.md) for more.
+## 2\. Call your flag in as few places as possible
+It should be easy to understand how feature flags affect your code. The more locations a flag is in, the more likely it is to cause problems. For example, a developer could remove the flag in one place but forget to remove it in another.
+If you expect to use a feature flag in multiple places, it's a good idea to wrap the flag in a single function or method. For example:
+JavaScript
+PostHog AI
+```javascript
+function useBetaFeature() {
+    return posthog.isFeatureEnabled('beta-feature')
+}
+```
+## 3\. Targeting
+PostHog evaluates flags based on the user's distinct ID, having different IDs can cause the same user to receive different flag values across different sessions, devices, and platforms. By [identifying](/docs/getting-started/identify-users.md) them, you can ensure consistent flag values.
+The same applies to identifying [groups](/docs/product-analytics/group-analytics.md) for group-level flags.
+For flags targeting anonymous users, such as signup flows or landing page experiments, consider using [device bucketing](/docs/feature-flags/device-bucketing.md) instead. This evaluates the flag based on the device ID, ensuring a consistent experience on the device even after the user logs in.
+## 4\. Use server-side local evaluation for faster flags
+Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.
+Evaluate flags locally when possible, since this enables you to resolve flags faster and with fewer API calls. See our docs on [local evaluation](/docs/feature-flags/local-evaluation.md) for more details.
+## 5\. Bootstrap flags on the client to make them available immediately
+Since there is a delay between initializing PostHog and fetching feature flags, feature flags are not always available immediately. This makes them unusable if you want to do something like redirecting a user to a different page based on a feature flag.
+To have your feature flags available immediately, you can initialize PostHog with precomputed values until it has had a chance to fetch them. This is called bootstrapping.
+See our docs on [bootstrapping](/docs/feature-flags/bootstrapping.md) for more details on how to do this.
+## 6\. Naming tips
+Good naming conventions for your flags makes them easier to understand and maintain. Below are tips for naming your flags:
+-   **Use descriptive names.** For example, `is_v2_billing_dashboard_enabled` is much clearer than `is_dashboard_enabled`.
+-   **Use name "types".** This helps organize them and makes their purpose clear. Types might include experiments, releases, and permissions. For example, instead of `new-billing`, they would be `new-billing-experiment` or `new-billing-release`.
+-   **Name flags to reflect their return type.** For example, `is_premium_user` for a boolean, `enabled_integrations` for an array, or `selected_theme` for a single string.
+-   **Use positive language for boolean flags.** For example, `is_premium_user` instead of `is_not_premium_user`. This helps avoid double negatives when checking the flag value (e.g. `if !is_not_premium_user` is confusing).
+## 7\. Roll out progressively
+When testing a change behind a feature flag, it is best to roll it out to a small group of users and increase that group over time. This is also known as a [phased rollout](/tutorials/phased-rollout.md). It enables you to identify any potential issues ahead of the full release.
+For example, at PostHog we often roll out the flag to just the responsible developer. It then moves on to the internal team, then beta users, and finally into a full rollout. This enables us to [test in production](/product-engineers/testing-in-production.md), get multiple rounds of feedback, identify issues, and polish the feature before the full release.
+## 8\. Clean up after yourself
+Leaving flags in your code for too long can confuse future developers and create technical debt, especially if it's already rolled out and integrated. Be sure to remove stale flags once they are completely rolled out or no longer needed.
+When you have many flags to clean up, use [bulk delete](/docs/feature-flags/creating-feature-flags.md#deleting-feature-flags-in-bulk) to select and delete multiple flags at once. Select flags using checkboxes (shift-click to select a range), or filter by name or status and use "select all matching" to select all flags that match your criteria. PostHog validates that flags aren't used by experiments, early access features, or other dependent flags before deletion.
+## 9\. Fallback to working code
+It's possible that a feature flag will return an [unexpected value](/docs/feature-flags/common-questions.md#my-feature-flag-called-events-show-none-empty-string-or-false-instead-of-my-variant-names). For example, if the flag is disabled or failed to load due to a network error.
+In this case, its best to check that the feature flag returns a valid expected value before using it. If it isn't, fallback to working code.
+## 10\. Use dependencies for complex rollouts
+For sophisticated feature rollouts, consider using [feature flag dependencies](/docs/feature-flags/dependencies.md) where one flag's activation depends on another flag's state. This is useful for:
+-   Enabling complex features only after foundational components are active
+-   Running experiments only on users with specific features enabled
+-   Creating safety mechanisms where critical flags must be enabled first
+When using dependencies, keep the dependency chains simple and avoid circular dependencies.
+## 11\. Reducing your bill
+We aim to be significantly cheaper than our competitors. To help you reduce your bill, we've created a [dedicated guide](/docs/feature-flags/cutting-costs.md) to estimating and reducing your feature flag costs.
+## 12\. Consistent flag evaluations across frontend and backend
+For feature flags with flag persistence enabled and used across both your frontend and backend, you will need to do one of the following to ensure the evaluation result of the flag is consistent between both environments:
+1.  Identify the user on the frontend and use the same identified distinct ID when evaluating the flag on the backend.
+JavaScript
+PostHog AI
+```javascript
+// Frontend: Identify the user
+posthog.identify('user123')
+// Backend: Use the same distinct ID
+const flagValue = await posthog.getFeatureFlag('my-flag', 'user123')
+```
+2.  If you are unable to call identify on the frontend, and only have access to the anonymous distinct ID when evaluating the flag on the backend, you can include the anonymous distinct ID as a person property override in the `getFeatureFlag` call.
+JavaScript
+PostHog AI
+```javascript
+// Frontend: Get the anonymous ID (before identify is called)
+const anonId = posthog.getAnonymousId()
+// Backend: Pass the anonymous ID as a person property override
+const flagValue = await posthog.getFeatureFlag(
+  'my-flag',
+  'user123', // identified distinct ID
+  {
+    personProperties: {
+      $anon_distinct_id: anonId
+    }
+  }
+)
+```
+### Community questions
+Ask a question
+### Was this page useful?
+HelpfulCould be better