feat: progressive loading for org packages

.claude/skills/vite-plus

@@ -0,0 +1 @@
+../../node_modules/vite-plus/skills/vite-plus

.trae/skills/vite-plus

@@ -0,0 +1 @@
+../../node_modules/vite-plus/skills/vite-plus

CLAUDE.md

@@ -0,0 +1,76 @@
+<!--VITE PLUS START-->
+
+# Using Vite+, the Unified Toolchain for the Web
+
+This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, but it invokes Vite through `vp dev` and `vp build`.
+
+## Vite+ Workflow
+
+`vp` is a global binary that handles the full development lifecycle. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+
+### Start
+
+- create - Create a new project from a template
+- migrate - Migrate an existing project to Vite+
+- config - Configure hooks and agent integration
+- staged - Run linters on staged files
+- install (`i`) - Install dependencies
+- env - Manage Node.js versions
+
+### Develop
+
+- dev - Run the development server
+- check - Run format, lint, and TypeScript type checks
+- lint - Lint code
+- fmt - Format code
+- test - Run tests
+
+### Execute
+
+- run - Run monorepo tasks
+- exec - Execute a command from local `node_modules/.bin`
+- dlx - Execute a package binary without installing it as a dependency
+- cache - Manage the task cache
+
+### Build
+
+- build - Build for production
+- pack - Build libraries
+- preview - Preview production build
+
+### Manage Dependencies
+
+Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the `packageManager` field in `package.json` or package manager-specific lockfiles.
+
+- add - Add packages to dependencies
+- remove (`rm`, `un`, `uninstall`) - Remove packages from dependencies
+- update (`up`) - Update packages to latest versions
+- dedupe - Deduplicate dependencies
+- outdated - Check for outdated packages
+- list (`ls`) - List installed packages
+- why (`explain`) - Show why a package is installed
+- info (`view`, `show`) - View package information from the registry
+- link (`ln`) / unlink - Manage local package links
+- pm - Forward a command to the package manager
+
+### Maintain
+
+- upgrade - Update `vp` itself to the latest version
+
+These commands map to their corresponding tools. For example, `vp dev --port 3000` runs Vite's dev server and works the same as Vite. `vp test` runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using `vp --version`. This is useful when researching documentation, features, and bugs.
+
+## Common Pitfalls
+
+- **Using the package manager directly:** Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations.
+- **Always use Vite commands to run tools:** Don't attempt to run `vp vitest` or `vp oxlint`. They do not exist. Use `vp test` and `vp lint` instead.
+- **Running scripts:** Vite+ commands take precedence over `package.json` scripts. If there is a `test` script defined in `scripts` that conflicts with the built-in `vp test` command, run it using `vp run test`.
+- **Do not install Vitest, Oxlint, Oxfmt, or tsdown directly:** Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands.
+- **Use Vite+ wrappers for one-off binaries:** Use `vp dlx` instead of package-manager-specific `dlx`/`npx` commands.
+- **Import JavaScript modules from `vite-plus`:** Instead of importing from `vite` or `vitest`, all modules should be imported from the project's `vite-plus` dependency. For example, `import { defineConfig } from 'vite-plus';` or `import { expect, test, vi } from 'vite-plus/test';`. You must not install `vitest` to import test utilities.
+- **Type-Aware Linting:** There is no need to install `oxlint-tsgolint`, `vp lint --type-aware` works out of the box.
+
+## Review Checklist for Agents
+
+- [ ] Run `vp install` after pulling remote changes and before getting started.
+- [ ] Run `vp check` and `vp test` to validate changes.
+<!--VITE PLUS END-->

app/composables/npm/useAlgoliaSearch.ts

@@ -214,11 +214,9 @@ export function useAlgoliaSearch() {
     }
   }
 
-  /** Fetch metadata for specific packages by exact name using Algolia's getObjects API. */
-  async function getPackagesByName(packageNames: string[]): Promise<NpmSearchResponse> {
-    if (packageNames.length === 0) {
-      return { isStale: false, objects: [], total: 0, time: new Date().toISOString() }
-    }
+  /** Fetch metadata for a single batch of packages (max 1000) by exact name. */
+  async function getPackagesByNameSlice(names: string[]): Promise<NpmSearchResult[]> {
+    if (names.length === 0) return []
 
     const response = await $fetch<{ results: (AlgoliaHit | null)[] }>(
       `https://${algolia.appId}-dsn.algolia.net/1/indexes/*/objects`,
@@ -229,7 +227,7 @@ export function useAlgoliaSearch() {
           'x-algolia-application-id': algolia.appId,
         },
         body: {
-          requests: packageNames.map(name => ({
+          requests: names.map(name => ({
             indexName,
             objectID: name,
             attributesToRetrieve: ATTRIBUTES_TO_RETRIEVE,
@@ -238,11 +236,31 @@ export function useAlgoliaSearch() {
       },
     )
 
-    const hits = response.results.filter((r): r is AlgoliaHit => r !== null && 'name' in r)
+    return response.results
+      .filter((r): r is AlgoliaHit => r !== null && 'name' in r)
+      .map(hitToSearchResult)
+  }
+
+  /** Fetch metadata for specific packages by exact name using Algolia's getObjects API. */
+  async function getPackagesByName(packageNames: string[]): Promise<NpmSearchResponse> {
+    if (packageNames.length === 0) {
+      return { isStale: false, objects: [], total: 0, time: new Date().toISOString() }
+    }
+
+    // Algolia getObjects has a limit of 1000 objects per request, so batch if needed
+    const BATCH_SIZE = 1000
+    const batches: string[][] = []
+    for (let i = 0; i < packageNames.length; i += BATCH_SIZE) {
+      batches.push(packageNames.slice(i, i + BATCH_SIZE))
+    }
+
+    const results = await Promise.all(batches.map(batch => getPackagesByNameSlice(batch)))
+    const allObjects = results.flat()
+
     return {
       isStale: false,
-      objects: hits.map(hitToSearchResult),
-      total: hits.length,
+      objects: allObjects,
+      total: allObjects.length,
       time: new Date().toISOString(),
     }
   }
@@ -349,5 +367,6 @@ export function useAlgoliaSearch() {
     searchWithSuggestions,
     searchByOwner,
     getPackagesByName,
+    getPackagesByNameSlice,
   }
 }

app/composables/npm/useOrgPackages.ts

@@ -1,9 +1,31 @@
+import type { NpmSearchResponse, NpmSearchResult, PackageMetaResponse } from '#shared/types'
+import { emptySearchResponse, metaToSearchResult } from './search-utils'
+import { mapWithConcurrency } from '#shared/utils/async'
+
+/** Number of packages to fetch metadata for in the initial load */
+const INITIAL_BATCH_SIZE = 250
+
+/** Max names per Algolia getObjects request */
+const ALGOLIA_BATCH_SIZE = 1000
+
+export interface OrgPackagesResponse extends NpmSearchResponse {
+  /** Total number of packages in the org (may exceed objects.length before loadAll) */
+  totalPackages: number
+}
+
+function emptyOrgResponse(): OrgPackagesResponse {
+  return {
+    ...emptySearchResponse(),
+    totalPackages: 0,
+  }
+}
+
 /**
- * Fetch all packages for an npm organization.
+ * Fetch packages for an npm organization with progressive loading.
  *
  * 1. Gets the authoritative package list from the npm registry (single request)
- * 2. Fetches metadata from Algolia by exact name (single request)
- * 3. Falls back to lightweight server-side package-meta lookups
+ * 2. Fetches metadata for the first batch immediately (fast SSR)
+ * 3. Remaining packages are loaded on-demand via `loadAll()`
  */
 export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
   const route = useRoute()
@@ -13,17 +35,24 @@ export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
     if (p === 'npm' || searchProvider.value === 'npm') return 'npm'
     return 'algolia'
   })
-  const { getPackagesByName } = useAlgoliaSearch()
+  const { getPackagesByNameSlice } = useAlgoliaSearch()
+
+  // Tracks all package names so loadAll() knows what to fetch
+  const allNames = shallowRef<string[]>([])
+  const loadedObjects = shallowRef<NpmSearchResult[]>([])
+
+  // Promise lock — scoped inside the composable to avoid cross-instance sharing
+  let loadAllPromise: Promise<void> | null = null
 
   const asyncData = useLazyAsyncData(
     () => `org-packages:${searchProviderValue.value}:${toValue(orgName)}`,
     async ({ ssrContext }, { signal }) => {
       const org = toValue(orgName)
       if (!org) {
-        return emptySearchResponse()
+        return emptyOrgResponse()
       }
 
-      // Get the authoritative package list from the npm registry (single request)
+      // Get the authoritative package list from the npm registry
       let packageNames: string[]
       try {
         const { packages } = await $fetch<{ packages: string[]; count: number }>(
@@ -32,7 +61,6 @@ export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
         )
         packageNames = packages
       } catch (err) {
-        // Check if this is a 404 (org not found)
         if (err && typeof err === 'object' && 'statusCode' in err && err.statusCode === 404) {
           const error = createError({
             statusCode: 404,
@@ -44,34 +72,120 @@ export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
           }
           throw error
         }
-        // For other errors (network, etc.), return empty array to be safe
         packageNames = []
       }
 
       if (packageNames.length === 0) {
-        return emptySearchResponse()
+        allNames.value = []
+        loadedObjects.value = []
+        return emptyOrgResponse()
       }
 
-      // Fetch metadata + downloads from Algolia (single request via getObjects)
+      allNames.value = packageNames
+      const initialNames = packageNames.slice(0, INITIAL_BATCH_SIZE)
+
+      // Fetch metadata for first batch
+      let initialObjects: NpmSearchResult[] = []
+
       if (searchProviderValue.value === 'algolia') {
         try {
-          const response = await getPackagesByName(packageNames)
-          if (response.objects.length > 0) {
-            return response
-          }
+          initialObjects = await getPackagesByNameSlice(initialNames)
         } catch {
-          // Fall through to npm registry path
+          // Fall through to npm fallback
         }
       }
 
-      // npm fallback: fetch lightweight metadata via server proxy
+      // Staleness guard
+      if (toValue(orgName) !== org) return emptyOrgResponse()
+
+      // npm fallback for initial batch
+      if (initialObjects.length === 0) {
+        const metaResults = await mapWithConcurrency(
+          initialNames,
+          async name => {
+            try {
+              return await $fetch<PackageMetaResponse>(
+                `/api/registry/package-meta/${encodePackageName(name)}`,
+                { signal },
+              )
+            } catch {
+              return null
+            }
+          },
+          10,
+        )
+
+        if (toValue(orgName) !== org) return emptyOrgResponse()
+
+        initialObjects = metaResults
+          .filter((meta): meta is PackageMetaResponse => meta !== null)
+          .map(metaToSearchResult)
+      }
+
+      loadedObjects.value = initialObjects
+
+      return {
+        isStale: false,
+        objects: initialObjects,
+        total: initialObjects.length,
+        totalPackages: packageNames.length,
+        time: new Date().toISOString(),
+      } satisfies OrgPackagesResponse
+    },
+    { default: emptyOrgResponse },
+  )
+
+  /** Load all remaining packages that weren't fetched in the initial batch. */
+  async function loadAll(): Promise<void> {
+    const names = allNames.value
+    if (names.length <= loadedObjects.value.length) return
+
+    // Reuse in-flight promise to prevent duplicate fetches
+    if (loadAllPromise) {
+      await loadAllPromise
+      return
+    }
+
+    loadAllPromise = _doLoadAll()
+    try {
+      await loadAllPromise
+    } finally {
+      loadAllPromise = null
+    }
+  }
+
+  async function _doLoadAll(): Promise<void> {
+    const names = allNames.value
+    const current = loadedObjects.value
+    if (names.length <= current.length) return
+
+    const org = toValue(orgName)
+    const remainingNames = names.slice(current.length)
+
+    let newObjects: NpmSearchResult[] = []
+
+    if (searchProviderValue.value === 'algolia') {
+      const batches: string[][] = []
+      for (let i = 0; i < remainingNames.length; i += ALGOLIA_BATCH_SIZE) {
+        batches.push(remainingNames.slice(i, i + ALGOLIA_BATCH_SIZE))
+      }
+
+      const results = await Promise.allSettled(batches.map(batch => getPackagesByNameSlice(batch)))
+
+      if (toValue(orgName) !== org) return
+
+      for (const result of results) {
+        if (result.status === 'fulfilled') {
+          newObjects.push(...result.value)
+        }
+      }
+    } else {
       const metaResults = await mapWithConcurrency(
-        packageNames,
+        remainingNames,
         async name => {
           try {
             return await $fetch<PackageMetaResponse>(
               `/api/registry/package-meta/${encodePackageName(name)}`,
-              { signal },
             )
           } catch {
             return null
@@ -80,19 +194,32 @@ export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
         10,
       )
 
-      const results: NpmSearchResult[] = metaResults
+      if (toValue(orgName) !== org) return
+
+      newObjects = metaResults
         .filter((meta): meta is PackageMetaResponse => meta !== null)
         .map(metaToSearchResult)
+    }
 
-      return {
+    if (newObjects.length > 0) {
+      const existingNames = new Set(current.map(o => o.package.name))
+      const deduped = newObjects.filter(o => !existingNames.has(o.package.name))
+      const all = [...current, ...deduped]
+      loadedObjects.value = all
+
+      // Update asyncData so the page sees the new objects
+      asyncData.data.value = {
         isStale: false,
-        objects: results,
-        total: results.length,
+        objects: all,
+        total: all.length,
+        totalPackages: names.length,
         time: new Date().toISOString(),
-      } satisfies NpmSearchResponse
-    },
-    { default: emptySearchResponse },
-  )
+      }
+    }
+  }
 
-  return asyncData
+  return {
+    ...asyncData,
+    loadAll,
+  }
 }