# Default session

**TL;DR:** a `defaultSession` in `config.json` sets the initial state loaded for
all users. Give each view an `init` block naming an assembly, a location and the
tracks to open — three lines you can write by hand or emit from a script. URL
params like `&session=` and `&loc=` build a fresh session and ignore the
`defaultSession`, unless
[`&extendSession=true`](https://jbrowse.org/jb2-staging/docs/urlparams#navigating-within-the-default-session)
is set, which navigates within it while keeping its tracks and settings.

A complete `config.json` that opens on a region of `ctgA` with the genes track
already showing:

```json
{
  "assemblies": [{ "name": "volvox", "uri": "volvox.2bit" }],
  "tracks": [
    {
      "type": "FeatureTrack",
      "trackId": "volvox_genes",
      "name": "Genes",
      "assemblyNames": ["volvox"],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "uri": "volvox.sort.gff3.gz"
      }
    }
  ],
  "defaultSession": {
    "name": "Session",
    "views": [
      {
        "type": "LinearGenomeView",
        "init": {
          "assembly": "volvox",
          "loc": "ctgA:1-50000",
          "tracks": ["volvox_genes"]
        }
      }
    ]
  }
}
```

`init` is resolved when the view attaches: it works out the `displayedRegions`
and the window the locus implies. [](https://jbrowse.org/jb2-staging/docs/automating) lists every field it
takes — `grow` to pad the locus for context, `highlight`, `tracklist`, `nav`,
and `displayedRegionNames` to open a whole-genome view of selected chromosomes.

A track entry can be an object when it needs display options:
`{ "trackId": "volvox_genes", "height": 200 }` opens the track 200px tall. Any
slot the display defines can be set this way.

View settings — `colorByCDS`, `showAminoAcids`, `showCenterLine`, `trackLabels`
— are properties of the view itself, so they sit _beside_ `init`:

```json session
{
  "defaultSession": {
    "name": "Session",
    "views": [
      {
        "type": "LinearGenomeView",
        "colorByCDS": true,
        "init": { "assembly": "volvox", "loc": "ctgA:1-50000" }
      }
    ]
  }
}
```

## Referencing tracks by trackId

`init.tracks` lists `trackId`s from the top-level `tracks` array; the session
never repeats an adapter. Any track the session opens must exist in that array
(or come from the assembly), or the session silently fails to open it. If a
pipeline regenerates `config.json` with different `trackId`s each build, the
`defaultSession` breaks along with every previously shared link, which is why
[trackIds must stay stable](https://jbrowse.org/jb2-staging/docs/config_guides/deploying#keep-trackids-stable-for-reproducible-links).

`jbrowse validate` reports a `defaultSession` naming a `trackId` that does not
exist.

To configure sessions via URL, see [URL parameters](https://jbrowse.org/jb2-staging/docs/urlparams).

## Sessions the app exports

The app's export-session option writes a full state snapshot: `id`s,
`displayedRegions` and the window (`windowStartBp`, `windowWidthBp`) spelled
out, and each track carrying a `configuration` reference and a `displays` array.
It is valid as a `defaultSession` and pastes straight in.

It is long, and hand-editing it comes with caveats:

- Every coordinate is resolved, so re-aiming the view means editing base-pair
  offsets.
- A display node accepts only that display's state-model properties, so a config
  slot written there — `"height": 250` on the display — is dropped without
  warning, where the same key works in an `init` track entry.

Use an export to capture a view you built by clicking, and read the locus and
track ids off it into an `init` block for anything you intend to keep editing.

## Shipping several named sessions

[`preConfiguredSessions`](https://jbrowse.org/jb2-staging/docs/config/jbrowserootconfig/#slot-preconfiguredsessions)
is a top-level array of the same session objects, each with a `name`, which
jbrowse-web and jbrowse-desktop list under File → "Pre-configured sessions...".
Use it where one instance serves several starting points — a figure per
publication, a locus per assay — that a reader should be able to switch between
without a link.

```json
{
  "defaultSession": { "name": "Overview", "views": [] },
  "preConfiguredSessions": [
    { "name": "LCT haplotype", "views": [] },
    { "name": "MHC region", "views": [] }
  ]
}
```

They are the same format as `defaultSession`: a `name` and a list of views with
`init` blocks, so a set of them is cheap to generate from whatever already knows
the loci. The same `trackId` caveat applies: a session naming a track that is
not in the top-level `tracks` array silently opens without it.

## See also

- [Intro to the config.json format](https://jbrowse.org/jb2-staging/docs/config_guides/intro)
- [URL parameters](https://jbrowse.org/jb2-staging/docs/urlparams)
- [](https://jbrowse.org/jb2-staging/docs/config_guides/deploying)