Skip to main content
The lists.yaml file defines the package lists displayed in your Shipped instance. Each list can contain multiple groups of packages from different providers.

​
File Structure

The configuration file is an array of list objects: 
- name: My Packages
  description: Tracking important releases
  groups:
    - name: Frontend
      displayName: Frontend Frameworks
      showName: true
      packages:
        - provider: npm
          name: react
          displayName: React
        - provider: npm
          name: vue

​
List Configuration

​
name
string
required
The unique name of the list.
​
description
string
Optional description of the list.
​
groups
array
Array of package groups within this list.

​
Group Configuration

​
groups[].name
string | number
required
The name or identifier of the group.
​
groups[].displayName
string
Display name for the group (overrides name in UI).
​
groups[].showName
boolean
Whether to show the group name in the UI.
​
groups[].packages
array
required
Array of packages in this group. Each package must specify a provider.

​
Package Configuration

All packages share these common fields:
​
provider
string
required
The package provider. Must be one of: github, npm, python, docker.
​
name
string
required
The package identifier (e.g., repository name, package name).
​
displayName
string
Custom display name for the package.
​
icon
string
URL or path to the package icon.
​
iconDark
string
URL or path to the dark mode icon.
​
extra
object
Provider-specific configuration options (see below).

​
Provider-Specific Options

​
GitHub

​
extra.includePrereleases
boolean
Include pre-release versions in the release list.
​
extra.maxReleases
number
Maximum number of releases to fetch and display.
Example: 
- provider: github
  name: vercel/next.js
  displayName: Next.js
  extra:
    includePrereleases: false
    maxReleases: 10

​
NPM

​
extra.tags
array
Array of NPM dist-tags to track (e.g., latest, next, beta).
​
extra.npmx
boolean
Use npmx.dev instead of npmjs.com as the external link to the package.
Example: 
- provider: npm
  name: react
  extra:
    tags: [latest, next, experimental]
    npmx: true

​
Python

​
extra.maxReleases
number
Maximum number of releases to fetch and display.
Example: 
- provider: python
  name: django
  extra:
    maxReleases: 15

​
Docker

​
extra.tags
array
Array of Docker tags to track (e.g., latest, stable).
Example: 
- provider: docker
  name: nginx
  extra:
    tags: [latest, stable, alpine]

​
Complete Example

- name: Production Stack
  description: Critical production dependencies
  groups:
    - name: frontend
      displayName: Frontend
      showName: true
      packages:
        - provider: npm
          name: react
          displayName: React
          extra:
            tags: [latest]
        - provider: npm
          name: next
          displayName: Next.js
          extra:
            tags: [latest, canary]
            npmx: true
    
    - name: backend
      displayName: Backend Services
      showName: true
      packages:
        - provider: python
          name: fastapi
          extra:
            maxReleases: 10
        - provider: docker
          name: postgres
          displayName: PostgreSQL
          extra:
            tags: [latest, alpine]
    
    - name: tools
      displayName: Development Tools
      showName: true
      packages:
        - provider: github
          name: vercel/turbo
          displayName: Turborepo
          extra:
            includePrereleases: false
            maxReleases: 5

Build docs developers (and LLMs) love

Get started for freeTalk to us