# Source

Read files from your project, GitHub, or your own data, and turn lists into paged API routes.

Hosts: Node, Docker, Cloudflare, Vercel, Netlify, Deno.

```ts [server/sources/docs.ts]
import { github, glob } from 'vite-hub/source'

// Markdown files from your docs folder
export const docs = glob({
  cwd: 'docs',
  include: '**/*.md',
})

// Files from a GitHub repository
export const handbook = github({
  repo: 'acme/handbook',
  ref: 'main',
})
```

```ts [server/api/intro.get.ts]
import { defineEventHandler } from 'h3'
import { createSource } from 'vite-hub/source'
import { docs } from '../sources/docs'

// Read one file: docs/intro.md
export default defineEventHandler(async () => {
  const reader = createSource(docs)
  return reader.read('intro.md')
})
```

```ts [server/api/handbook.get.ts]
import { defineEventHandler } from 'h3'
import { createSource } from 'vite-hub/source'
import { handbook } from '../sources/docs'

// List the path of every file in the repository
export default defineEventHandler(async () => {
  const reader = createSource(handbook)
  return reader.keys()
})
```

```ts [server/collections/articles.ts]
import {
  array,
  defineCollection,
} from 'vite-hub/source'

// ViteHub serves this list at /api/articles
export const articles = defineCollection({
  source: array([
    { slug: 'hello', title: 'Hello', tag: 'news' },
    { slug: 'vite', title: 'Why Vite', tag: 'guide' },
  ], {
    filters: ['tag'],
    search: ['title'],
  }),
})
```

```vue [app/pages/articles.vue]
<script setup lang="ts">
import { useCollection } from 'vite-hub/source/client'

// Load the guides, one page at a time
const { items, hasMore, loadMore } =
  useCollection('articles', {
    filter: { tag: 'guide' },
  })
</script>

<template>
  <p v-for="article in items" :key="article.slug">
    {{ article.title }}
  </p>
  <button v-if="hasMore" @click="loadMore()">
    More
  </button>
</template>
```

### [Ready-made readers](https://vitehub.dev/docs/source/configure#source-loader-options)

Read a file, a folder, or a GitHub repository. Your files do not change.

### [Read from any route](https://vitehub.dev/docs/source/server-api#source-reader-api)

`createSource()` opens a reader. `keys()`, `read()`, and `list()` get files.

### [Bring your own data](https://vitehub.dev/docs/source/configure#source-object-contract)

`defineSource()` reads from anywhere. Give it the keys and a way to load one item. TypeScript infers the types.

### [Turn a list into an API route](https://vitehub.dev/docs/source/server-api#expose-a-typed-collection)

A file in `server/collections` becomes a GET route. In Vue, `useCollection()` loads it page by page.


### [Filter and search a list](https://vitehub.dev/docs/source/server-api#collections-over-an-array)

`array()` adds filters, search, and counts to a list that fits in memory.

### [Keep a list private](https://vitehub.dev/docs/source/server-api#protect-a-collection)

`authorize` allows only signed-in users. Others get `401` or `403`.

Use Source to read files, records, or external resources through a typed, read-only loader. Sources provide context; they do not grant write authority.

Choose the narrowest loader and scope its root, branch, or query. Validate source provenance and access before passing content to an Agent or route.

Prove a successful read, an out-of-scope path, missing content, and the returned metadata or revision.

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/source.md) (this page)
- [Get started](https://vitehub.dev/raw/docs/source/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/source/configure.md)
- [Server API](https://vitehub.dev/raw/docs/source/server-api.md)
- [Hosts](https://vitehub.dev/raw/docs/source/hosts.md)
- [Limits and errors](https://vitehub.dev/raw/docs/source/limits-and-errors.md)

Next: [SOURCE_R0001](https://vitehub.dev/raw/docs/source/diagnostics/source_r0001.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
