# Packages in Fern Definition

> Fern Definition enables the reuse of API type and error names across packages, and can configure the structure of your API documentation.

## What is a package?

Every folder in your API definition is a package.

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />

    <File name="generators.yml" />

    <Folder name="definition" defaultOpen comment="root package">
      <File name="api.yml" />

      <File name="projects.yml" />

      <Folder name="roles" defaultOpen comment="nested package">
        <File name="admin.yml" />
      </Folder>
    </Folder>
  </Folder>
</Files>

The generated SDK will match the hierarchy of your API definition.

<CodeBlock title="Generated SDK">
  ```ts
  const client = new Client();

  // calling endpoint defined in projects.yml
  client.projects.get();

  // calling endpoint defined in roles/admin.yml
  client.roles.admin.get();
  ```
</CodeBlock>

## Package configuration

Each package can have a special definition file called `__package__.yml`. Like any
other definition file, it can contain [imports](/learn/api-definition/fern/imports),
[types](/learn/api-definition/fern/types), [endpoints](/learn/api-definition/fern/endpoints),
and [errors](/learn/api-definition/fern/errors).

Endpoints in `__package__.yml` will appear at the root of the package.
For example, the following generated SDK:

<CodeBlock title="Generated SDK">
  ```ts
  const client = new Client();

  client.getProjects();
  ```
</CodeBlock>

would have a `fern/` folder:

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />

    <File name="generators.yml" />

    <Folder name="definition" defaultOpen>
      <File name="__package__.yml" highlighted />

      <File name="roles.yml" />
    </Folder>
  </Folder>
</Files>

that contains the following`__package__.yml`:

<CodeBlock title="__package__.yml">
  ```yaml
  service:
    base-path: ""
    auth: false
    endpoints:
      getProjects:
        method: GET
        path: ""
        response: list<Project>
  ```
</CodeBlock>

## Namespacing

Each package has its own namespace. This means you can reuse type names and
error names across packages.

This is useful when versioning your APIs. For example, when you want to
increment your API version, you can copy the existing API
to a new package and start making changes. If the new API version reuses
certain types or errors, that's okay because the two APIs live in different
packages.

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />

    <File name="generators.yml" />

    <Folder name="definition" defaultOpen>
      <File name="api.yml" />

      <Folder name="roles" defaultOpen>
        <Folder name="v1" defaultOpen>
          <File name="admin.yml" comment="type names can overlap with v2/admin.yml" />
        </Folder>

        <Folder name="v2" defaultOpen>
          <File name="admin.yml" />
        </Folder>
      </Folder>
    </Folder>
  </Folder>
</Files>

## Navigation

`__package__.yml` also allows you to configure the navigation order
of your services. This is relevant when you want to control the display
of your documentation.

For example, let's say you have the following `fern/` folder:

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />

    <File name="generators.yml" />

    <Folder name="definition" defaultOpen>
      <File name="projects.yml" />

      <File name="roles.yml" />

      <File name="users.yml" />
    </Folder>
  </Folder>
</Files>

Your API will be sorted alphabetically: projects, roles, then users. If you
want to control the navigation, you can add a `__package__.yml` file
and configure the order:

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />

    <File name="generators.yml" />

    <Folder name="definition" defaultOpen>
      <File name="__package__.yml" comment="New File" />

      <File name="projects.yml" />

      <File name="roles.yml" />

      <File name="users.yml" />
    </Folder>
  </Folder>
</Files>

<CodeBlock title="__package__.yml">
  ```yaml
  navigation: 
    - users.yml
    - roles.yml
    - projects.yml
  ```
</CodeBlock>