> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitfield.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Store files inside a package

> Keep package-owned bytes declared by the package file instead of letting consumers read loose app files.

<div className="bf-article">
  <p className="bf-lead">
    When a package ships files or bytes, keep them inside the package file. Consumer packages should receive named data or target replies, not random file paths into another package.
  </p>

  A help package ships markdown, a theme package ships images, and a file-preview package ships a small parser. A consumer wants the rendered result. The consumer should not read arbitrary files from the package folder.

  Package bytes should move with the package. Consumers should use public reads or requests, not private file paths that happen to work today.

  ## Traditional app shape

  ```ts theme={null}
  const helpText = await fetch('/packages/help/content/getting-started.md');
  ```

  or:

  ```ts theme={null}
  import helpText from '../help/content/getting-started.md?raw';
  ```

  Now the consumer depends on the help package's private file path. Rename the folder and consumers break.

  ## Bitfield shape

  ```text theme={null}
  help package file declares package-owned bytes
  Runtime Kit admits the bytes with the package
  consumer reads prepared help content or asks a help target
  ```

  The package decides what bytes it brings. The consumer uses the public name exposed by the package file.

  ## Boundary example

  ```json theme={null}
  {
    "package": "help-package",
    "things": [
      {
        "type": "stored_bytes",
        "address": "package::help-package::bytes::getting-started",
        "file": "content/getting-started.md",
        "content_type": "text/markdown"
      }
    ]
  }
  ```

  The important part is not the exact content. The important part is the boundary: the package file reference stays inside the package.

  ## Four file situations

  ### Help markdown

  ### Private help path

  ```ts theme={null}
  const help = await fetch('/packages/help/content/getting-started.md').then((r) => r.text());
  ```

  ### Prepared help read

  ```ts theme={null}
  const help = readInput('getting-started-help');
  ```

  The help package owns the file. The consumer reads prepared help content.

  ### Preview HTML

  ### Private preview bundle

  ```ts theme={null}
  import previewHtml from '../project-preview/dist/index.html?raw';
  ```

  ### Prepared preview surface

  ```ts theme={null}
  const previewSurface = readInput('project-preview-surface');
  ```

  The preview package decides how the surface is prepared. The shell receives a public view.

  ### Review template

  ### Private template import

  ```ts theme={null}
  import template from '../review-package/templates/review.md';
  ```

  ### Prepared template read

  ```ts theme={null}
  const reviewTemplate = readInput('review-template');
  ```

  The package can ship the template as package material. The caller should not read the package folder directly.

  ### Search index

  ### Private search index

  ```ts theme={null}
  import index from '../help/search-index.json';
  ```

  ### Search through the package target

  ```ts theme={null}
  await sendRequestToBitfieldTarget({
    target: 'help.search',
    payload: { query },
  });
  ```

  The caller asks for search results. The help package can change its index format without breaking the caller.

  ## Consumer rules

  | Rule                                                                          | Meaning                                           |
  | ----------------------------------------------------------------------------- | ------------------------------------------------- |
  | A consumer may read a public data name.                                       | It can use the handle the package exposes.        |
  | A consumer may send a public action request.                                  | It can ask the package to do work.                |
  | A consumer may not import package files directly.                             | Folder structure is not public API.               |
  | A consumer may not copy bytes into app code.                                  | Package material should stay package material.    |
  | A consumer may not assume file format unless the package exposes that format. | The public name is the data name or target reply. |

  ## What this prevents

  | Bad shape                                  | Why it breaks                                    | Better shape                                                    |
  | ------------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------- |
  | Consumer imports another package's file.   | Folder structure becomes public API by accident. | Consumer reads named data.                                      |
  | Consumer builds a local filesystem path.   | It only works on one machine/shell.              | Package declares package-owned bytes.                           |
  | Package references files outside itself.   | The package cannot move cleanly.                 | Keep package file references inside the package folder.         |
  | App code copies package bytes into itself. | Data and code boundaries blur.                   | Keep bytes in package material and expose a public read/target. |

  React is one adapter that might render the bytes, but React does not define the package file. A web shell, native shell, terminal shell, or future adapter should receive named data from the same package-owned material.

  ## Review checklist

  | Check                                               | Good answer                                            |
  | --------------------------------------------------- | ------------------------------------------------------ |
  | Does consumer code import another package file?     | No. It reads a data name or sends an action request.   |
  | Does the package reference material outside itself? | No. Package material stays inside the package file.    |
  | Does the consumer assume the file format?           | Only when the public data name or reply shape says so. |
  | Can the package move without breaking consumers?    | Yes. Consumers rely on public names, not folders.      |

  ## Full before and after

  ### Traditional feature request

  "Add a help panel that shows package help and lets the user search it."

  ### Bad implementation

  ```ts theme={null}
  import help from '../help/content/getting-started.md?raw';
  import searchIndex from '../help/search-index.json';

  export function HelpPanel() {
    return renderHelp(help, searchIndex);
  }
  ```

  This consumer now depends on two package files and one package layout. If the help package changes how it stores content or search data, the consumer breaks.

  ### Public package version

  ```ts theme={null}
  const help = readInput('getting-started-help');

  const results = await sendRequestToBitfieldTarget({
    target: 'help.search',
    payload: { query },
  });
  ```

  The consumer gets content and search through public names. The package can keep markdown, JSON, a generated index, or something else behind that boundary.

  For React, Swift, Kotlin, terminal, or future adapters, the consumer rule stays the same: do not read package files directly.

  ## Good consumer code

  ```ts theme={null}
  const help = readInput('getting-started-help');
  ```

  ### React adapter example

  ```tsx theme={null}
  const help = useBitfieldData<{ title: string; body: string }>('getting-started-help');
  ```

  The consumer asks for help content by public input name. It does not import or parse the package file that produced it.

  ## Review check

  If consumer code imports `../some-package/content/file.md`, stop. Package files are package material. Consumers should read a data name or request a target.

  ## Next

  * Build package-owned bytes: [Package-owned file](/runtime-kit/cookbook/package-owned-file)
  * Learn package rules: [Packages](/runtime-kit/packages)
  * Look up boundary fields: [Package file](/reference/package-boundary)
</div>