[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7EX8ZR21GDFM2G34RXXVB9E":3,"skill-same:01M7EX8ZR21GDFM2G34RXXVB9E":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7EX8ZR21GDFM2G34RXXVB9E","nuqs-url-state",null,"nuqs URL state management patterns for Next.js App Router. Activate when reading or writing URL search params, building filters, pagination, tabs, or any state that should live in the URL.","Phenomenon-Studio\u002Fphenomenon-configs","Phenomenon-Studio","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F85674486?v=4","01M7EX2X2JF76C91JB202QMQHW","Phenomenon studio","01M7EX2X37T2C5FBHAH4B60YMX",1,"MIT","https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs\u002Fblob\u002Fmain\u002Ftemplate\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'next' else '' }}\u002F.agents\u002Fskills\u002Fnuqs-url-state\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: nuqs-url-state\ndescription: nuqs URL state management patterns for Next.js App Router. Activate when reading or writing URL search params, building filters, pagination, tabs, or any state that should live in the URL.\n---\n\n# nuqs URL State Patterns\n\nnuqs provides type-safe URL search param state for Next.js App Router. Use it for any state that should be shareable, bookmarkable, or survive a page refresh.\n\n## When to Apply\n\n- Filter panels, search inputs, sort controls\n- Pagination (page, pageSize)\n- Tabs or view mode toggles that should be deep-linkable\n- Any state where \"copy the URL\" should reproduce the current view\n\nDo NOT use nuqs for ephemeral UI state (modals, hover states, transient animations). Use `useState` for those.\n\n## Core Rules\n\n### 1. Always pair with a Zod schema for validation\n\nnuqs parsers validate on parse, but complex shapes need explicit Zod schemas at the service boundary.\n\n```ts\n\u002F\u002F BAD — raw string, no validation\nconst [sort] = useQueryState('sort');\n\n\u002F\u002F GOOD — typed parser\nimport { parseAsStringLiteral } from 'nuqs';\nconst SORT_OPTIONS = ['asc', 'desc'] as const;\nconst [sort, setSort] = useQueryState('sort', parseAsStringLiteral(SORT_OPTIONS).withDefault('asc'));\n```\n\n### 2. Use `useQueryStates` for related params\n\nGroup related params to avoid race conditions and unnecessary re-renders.\n\n```ts\n\u002F\u002F BAD — two separate hooks, two URL updates\nconst [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));\nconst [search, setSearch] = useQueryState('search', parseAsString.withDefault(''));\n\n\u002F\u002F GOOD — atomic update\nconst [params, setParams] = useQueryStates({\n  page: parseAsInteger.withDefault(1),\n  search: parseAsString.withDefault(''),\n});\n```\n\n### 3. Reset page when filters change\n\nWhen filters update, page must reset to 1 in the same atomic call.\n\n```ts\nconst handleSearchChange = (search: string) => {\n  setParams({ search, page: 1 }); \u002F\u002F reset together\n};\n```\n\n### 4. Use `shallow: false` only when SSR needs to re-run\n\nBy default nuqs uses shallow routing (no server round-trip). Set `shallow: false` only when changing params must trigger a Server Component re-render (e.g., server-side filtered data).\n\n```ts\nconst [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({ shallow: false }));\n```\n\n### 5. Server Components: use `searchParams` prop, not `useQueryState`\n\n`useQueryState` is a client hook. In Server Components, read params from the `searchParams` prop directly and validate with a Zod schema.\n\nRoute where the search parameters parsing is needed, should create a `searchParams.ts` file and export a loader that describes schema:\n\n```ts\n\u002F\u002F src\u002Fapp\u002Fproducts\u002FsearchParams.ts\nimport { createLoader, parseAsInteger, parseAsString } from 'nuqs\u002Fserver';\n\nexport const loadProductsSearchParams = createLoader({\n    page: parseAsInteger.withDefault(1),\n    search: parseAsString.withDefault(''),\n});\n```\n\n```ts\n\u002F\u002F app\u002Fproducts\u002Fpage.tsx (Server Component)\nimport type { NextPage } from 'next';\nimport { loadProductsSearchParams } from '.\u002FsearchParams';\n\nconst Page: NextPage\u003C{ searchParams: Promise\u003CRecord\u003Cstring, string>> }> = ({ searchParams }) => {\n  const awaitedSearchParams = await loadProductsSearchParams(searchParams);\n  \u002F\u002F pass parsed to prefetchQuery or directly to RSC data fetching\n}\n\nexport default Page;\n```\n\n### 6. Define parsers as constants, not inline\n\nInline parser definitions recreate objects on every render. Repetitive parsers should be hoisted to global search params scope at `src\u002Flib\u002FsearchParams\u002Fclient.ts` and `src\u002Flib\u002FsearchParams\u002Fserver.ts`. Client and server should have the same parsers. CLient ones are applicable in client component only. Server ones are applicable in `src\u002Fapp\u002F*\u002FsearchParams.ts` files and in client component if `createSearchParamsCache` constant is used.\n\n```ts\n\u002F\u002F BAD\nconst [page] = useQueryState('page', parseAsInteger.withDefault(1));\n\n\u002F\u002F GOOD — hoist to module scope\nimport { parseAsPage } from '@\u002Flib\u002FsearchParams\u002Fclient';\n\nconst [page] = useQueryState('page', parseAsPage);\n```\n\n### 7. Use `createSearchParamsCache` for RSC + client sync\n\nWhen the same params are read in both Server and Client Components, use `createSearchParamsCache` to avoid duplication.\n\n```ts\n\u002F\u002F src\u002Flib\u002FsearchParams\u002Fserver.ts\nimport { createSearchParamsCache, parseAsInteger, parseAsString } from 'nuqs\u002Fserver';\n\nexport const productSearchParamsCache = createSearchParamsCache({\n  page: parseAsPage,\n  search: parseAsString.withDefault(''),\n});\nexport type ProductSearchParams = ReturnType\u003Ctypeof productSearchParamsCache.parse>;\n```\n\n```ts\n\u002F\u002F In Server Component layout or page:\nproductSearchParamsCache.parse(searchParams);\n\n\u002F\u002F In Client Component:\nimport { useQueryStates } from 'nuqs';\nimport { productSearchParamsCache } from '@\u002Flib\u002FsearchParams\u002Fserver';\nconst [params] = useQueryStates(productSearchParamsCache.parsers);\n```\n\n## Common Parsers Reference\n\n| Data type | Parser |\n|---|---|\n| String | `parseAsString` |\n| Integer | `parseAsInteger` |\n| Float | `parseAsFloat` |\n| Boolean | `parseAsBoolean` |\n| String enum | `parseAsStringLiteral(['a', 'b'])` |\n| JSON object | `parseAsJson(zodSchema.parse)` |\n| Array | `parseAsArrayOf(parseAsString)` |\n| ISO date | `parseAsIsoDateTime` |\n\n## Integration with TanStack Query\n\nPass nuqs params into query options directly — they are already stable primitives.\n\n```ts\nconst [params] = useQueryStates(productSearchParamsCache.parsers);\nconst { data } = useQuery(productsQueryOptions(params));\n```\n\nInvalidation does not need to touch nuqs — query keys derived from params will naturally update when params change.\n","# nuqs URL State Patterns\n\nnuqs provides type-safe URL search param state for Next.js App Router. Use it for any state that should be shareable, bookmarkable, or survive a page refresh.\n\n## When to Apply\n\n- Filter panels, search inputs, sort controls\n- Pagination (page, pageSize)\n- Tabs or view mode toggles that should be deep-linkable\n- Any state where \"copy the URL\" should reproduce the current view\n\nDo NOT use nuqs for ephemeral UI state (modals, hover states, transient animations). Use `useState` for those.\n\n## Core Rules\n\n### 1. Always pair with a Zod schema for validation\n\nnuqs parsers validate on parse, but complex shapes need explicit Zod schemas at the service boundary.\n\n```ts\n\u002F\u002F BAD — raw string, no validation\nconst [sort] = useQueryState('sort');\n\n\u002F\u002F GOOD — typed parser\nimport { parseAsStringLiteral } from 'nuqs';\nconst SORT_OPTIONS = ['asc', 'desc'] as const;\nconst [sort, setSort] = useQueryState('sort', parseAsStringLiteral(SORT_OPTIONS).withDefault('asc'));\n```\n\n### 2. Use `useQueryStates` for related params\n\nGroup related params to avoid race conditions and unnecessary re-renders.\n\n```ts\n\u002F\u002F BAD — two separate hooks, two URL updates\nconst [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));\nconst [search, setSearch] = useQueryState('search', parseAsString.withDefault(''));\n\n\u002F\u002F GOOD — atomic update\nconst [params, setParams] = useQueryStates({\n  page: parseAsInteger.withDefault(1),\n  search: parseAsString.withDefault(''),\n});\n```\n\n### 3. Reset page when filters change\n\nWhen filters update, page must reset to 1 in the same atomic call.\n\n```ts\nconst handleSearchChange = (search: string) => {\n  setParams({ search, page: 1 }); \u002F\u002F reset together\n};\n```\n\n### 4. Use `shallow: false` only when SSR needs to re-run\n\nBy default nuqs uses shallow routing (no server round-trip). Set `shallow: false` only when changing params must trigger a Server Component re-render (e.g., server-side filtered data).\n\n```ts\nconst [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({ shallow: false }));\n```\n\n### 5. Server Components: use `searchParams` prop, not `useQueryState`\n\n`useQueryState` is a client hook. In Server Components, read params from the `searchParams` prop directly and validate with a Zod schema.\n\nRoute where the search parameters parsing is needed, should create a `searchParams.ts` file and export a loader that describes schema:\n\n```ts\n\u002F\u002F src\u002Fapp\u002Fproducts\u002FsearchParams.ts\nimport { createLoader, parseAsInteger, parseAsString } from 'nuqs\u002Fserver';\n\nexport const loadProductsSearchParams = createLoader({\n    page: parseAsInteger.withDefault(1),\n    search: parseAsString.withDefault(''),\n});\n```\n\n```ts\n\u002F\u002F app\u002Fproducts\u002Fpage.tsx (Server Component)\nimport type { NextPage } from 'next';\nimport { loadProductsSearchParams } from '.\u002FsearchParams';\n\nconst Page: NextPage\u003C{ searchParams: Promise\u003CRecord\u003Cstring, string>> }> = ({ searchParams }) => {\n  const awaitedSearchParams = await loadProductsSearchParams(searchParams);\n  \u002F\u002F pass parsed to prefetchQuery or directly to RSC data fetching\n}\n\nexport default Page;\n```\n\n### 6. Define parsers as constants, not inline\n\nInline parser definitions recreate objects on every render. Repetitive parsers should be hoisted to global search params scope at `src\u002Flib\u002FsearchParams\u002Fclient.ts` and `src\u002Flib\u002FsearchParams\u002Fserver.ts`. Client and server should have the same parsers. CLient ones are applicable in client component only. Server ones are applicable in `src\u002Fapp\u002F*\u002FsearchParams.ts` files and in client component if `createSearchParamsCache` constant is used.\n\n```ts\n\u002F\u002F BAD\nconst [page] = useQueryState('page', parseAsInteger.withDefault(1));\n\n\u002F\u002F GOOD — hoist to module scope\nimport { parseAsPage } from '@\u002Flib\u002FsearchParams\u002Fclient';\n\nconst [page] = useQueryState('page', parseAsPage);\n```\n\n### 7. Use `createSearchParamsCache` for RSC + client sync\n\nWhen the same params are read in both Server and Client Components, use `createSearchParamsCache` to avoid duplication.\n\n```ts\n\u002F\u002F src\u002Flib\u002FsearchParams\u002Fserver.ts\nimport { createSearchParamsCache, parseAsInteger, parseAsString } from 'nuqs\u002Fserver';\n\nexport const productSearchParamsCache = createSearchParamsCache({\n  page: parseAsPage,\n  search: parseAsString.withDefault(''),\n});\nexport type ProductSearchParams = ReturnType\u003Ctypeof productSearchParamsCache.parse>;\n```\n\n```ts\n\u002F\u002F In Server Component layout or page:\nproductSearchParamsCache.parse(searchParams);\n\n\u002F\u002F In Client Component:\nimport { useQueryStates } from 'nuqs';\nimport { productSearchParamsCache } from '@\u002Flib\u002FsearchParams\u002Fserver';\nconst [params] = useQueryStates(productSearchParamsCache.parsers);\n```\n\n## Common Parsers Reference\n\n| Data type | Parser |\n|---|---|\n| String | `parseAsString` |\n| Integer | `parseAsInteger` |\n| Float | `parseAsFloat` |\n| Boolean | `parseAsBoolean` |\n| String enum | `parseAsStringLiteral(['a', 'b'])` |\n| JSON object | `parseAsJson(zodSchema.parse)` |\n| Array | `parseAsArrayOf(parseAsString)` |\n| ISO date | `parseAsIsoDateTime` |\n\n## Integration with TanStack Query\n\nPass nuqs params into query options directly — they are already stable primitives.\n\n```ts\nconst [params] = useQueryStates(productSearchParamsCache.parsers);\nconst { data } = useQuery(productsQueryOptions(params));\n```\n\nInvalidation does not need to touch nuqs — query keys derived from params will naturally update when params change.\n",{"name":5,"description":7},"main","a5c9ac2f39c1611831e417faea2e6d635699d9b5","template\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'next' else '' }}\u002F.agents\u002Fskills\u002Fnuqs-url-state",0,"https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs","https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio","https:\u002F\u002Fphenomenonstudio.com\u002F","Phenomenon is a digital product studio bolstering a core team of world-class developers, designers, and a flexible network of multi-specialized talent. ","2026-10-23 17:20:31",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add Phenomenon-Studio\u002Fphenomenon-configs --skill nuqs-url-state",{"tool":39,"command":40},"bunx","bunx skills add Phenomenon-Studio\u002Fphenomenon-configs --skill nuqs-url-state",{"tool":42,"command":43},"pnpm","pnpm dlx skills add Phenomenon-Studio\u002Fphenomenon-configs --skill nuqs-url-state","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs\u002Fblob\u002Fmain\u002Ftemplate\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'next' else '' }}\u002F.agents\u002Fskills\u002Fnuqs-url-state\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M7EXBNNR8YZB8PD7J8ZAB5FP","web-security","Enforce web security and avoid security vulnerabilities.","https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs\u002Fblob\u002Fmain\u002Ftemplate\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'vite' else '' }}\u002F.claude\u002Fskills\u002Fweb-security\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7EXBJGWKB32NY4R2V141G0S","typescript","Write clean, efficient TypeScript code that follows project conventions and advanced type patterns. Use when writing or reviewing TypeScript code, defining types, creating generics, handling errors, or working with React components, Zod schemas, and TanStack libraries.","https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs\u002Fblob\u002Fmain\u002Ftemplate\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'vite' else '' }}\u002F.claude\u002Fskills\u002Ftypescript\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7EXBESDHFPHAZKN292SDB6E","tanstack-router","TanStack Router patterns for this repo — file-based routing, auth guards, search params, data loading, TanStack Query integration, navigation, and code splitting. Use when creating routes, adding pages, implementing auth flows, working with search\u002Fpath params, or integrating loaders with TanStack Query.","https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs\u002Fblob\u002Fmain\u002Ftemplate\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'vite' else '' }}\u002F.claude\u002Fskills\u002Ftanstack-router\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7EXBAZW0KSMGVDB9DW157SD","tanstack-query","TanStack Query patterns for this repo — queryOptions\u002FmutationOptions factories, query key hierarchies, service layer integration, optimistic updates, Suspense usage, error handling, and TanStack Router data loading. Use when creating queries, mutations, API services, query keys, cache invalidation, optimistic updates, or integrating data fetching with routes.","https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs\u002Fblob\u002Fmain\u002Ftemplate\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'vite' else '' }}\u002F.claude\u002Fskills\u002Ftanstack-query\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7EXB6X2TG4HYWCYB293581T","tanstack-form","Build forms using TanStack Form with the project's useAppForm composition, composable field components, Zod validation schemas, FormFieldWrapper error tracking, and form.AppField vs form.Field patterns. Use when creating new forms, adding form fields, writing form validation, or working with TanStack Form in this project.","https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs\u002Fblob\u002Fmain\u002Ftemplate\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'vite' else '' }}\u002F.claude\u002Fskills\u002Ftanstack-form\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7EXB4EXHFSSVY64QQAE77SA","react","Build clean, modern React components that apply common best practices and avoid common pitfalls like unnecessary state management or useEffect usage.","https:\u002F\u002Fgithub.com\u002FPhenomenon-Studio\u002Fphenomenon-configs\u002Fblob\u002Fmain\u002Ftemplate\u002Fproject\u002F{{ '.' if scope == 'app' and stack == 'vite' else '' }}\u002F.claude\u002Fskills\u002Freact\u002FSKILL.md",[],[]]