# @atlaskit/atlassian-context

> Provides perimeter-specific URL resolution and helps identify which environment a product is running in.

Latest version **1.2.0** (published 2026-09-15) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @atlaskit/atlassian-context
pnpm add @atlaskit/atlassian-context
yarn add @atlaskit/atlassian-context
bun add @atlaskit/atlassian-context
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2026-09-15 |
| First published | 2024-06-12 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 139.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Atlassian Pty Ltd |
| Maintainers | atlassianartifactteam |

## Links

- npm: https://www.npmjs.com/package/@atlaskit/atlassian-context
- Repository: https://bitbucket.org/atlassian/atlassian-frontend-monorepo
- Homepage: https://bitbucket.org/atlassian/atlassian-frontend-monorepo#readme
- Issues: https://bitbucket.org/atlassian/atlassian-frontend-monorepo/issues
- npm.io page: https://npm.io/package/@atlaskit/atlassian-context

## Dependencies (1)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.0.0

## Recent versions

- 1.2.0 (latest) — 2026-09-15
- 1.1.1 — 2026-07-15
- 1.1.0 — 2026-07-14
- 1.0.0 — 2026-06-16
- 0.11.0 — 2026-06-12
- 0.10.0 — 2026-06-04
- 0.9.0 — 2026-05-13
- 0.8.0 — 2026-04-08
- 0.7.0 — 2026-04-07
- 0.6.1 — 2026-03-03
- 0.6.0 — 2025-09-17
- 0.5.0 — 2025-08-19
- 0.4.0 — 2025-07-30
- 0.3.2 — 2025-07-25
- 0.3.1 — 2025-07-02
- … 6 more at https://npm.io/package/@atlaskit/atlassian-context/versions

## README

# Environment context library

Provides perimeter-specific URL resolution and helps identify which environment a product is running in.

Read more about the original considerations here:
https://hello.atlassian.net/wiki/spaces/FEDRAMP/pages/2561199256/UI+Isolation

## Ownership
In 2025, ownership of the library was transferred to Regulated Industries. Please reach out to #help-cross-boundary for any help.


## Installation

```sh
npm install @atlaskit/atlassian-context --save
```

## Prerequisites

> **_NOTE:_** Skip these pre-requisites if onboarding onto library for the first time in May 2025 onwards. These pre-requisites are for the original `configure()`, `getATLContextDomain()`, `getATLContextUrl()`, and `isFedRamp()` functions, which be will be deprecated in the nearish future.

In order for `@atlaskit/atlassian-context` to work correctly `window.ATL_CONTEXT_DOMAIN` has to be
set on the page. Products must either have the data already on window or call `configure()`, before
calling any get\*() calls. Otherwise `getATLContextDomain()` and `getATLContextUrl()` will use
fallbacks and potentially return an uncorrected response.

If using the deprecated `isFedRamp()` method, also
`window.UNSAFE_ATL_CONTEXT_BOUNDARY = 'fedramp-moderate' | 'commercial'` has to be set on the page.
Otherwise, you could potentially serve environments with code that it is not relevant to them.

## Setup

> **_NOTE:_** Skip this setup if onboarding onto library for the first time in May 2025 onwards. Access to `window.ATL_CONTEXT_DOMAIN` and `window.UNSAFE_ATL_CONTEXT_BOUNDARY` is only required for the `configure()`, `getATLContextDomain()`, `getATLContextUrl()`, and `isFedRamp()` functions, which be will be deprecated in the nearish future.

This library must be initialised in order to return the correct results. How it gets initialised
will depend on your service. The configuration data may be loaded by any Micros service from
[Config Registry](https://bitbucket.org/atlassian/shared-environment-config). For any further help,
reach out to [#help-config-injector](https://atlassian.enterprise.slack.com/archives/C0611PE6WDU).

**⚠️ Warning: `window.MICROS_PERIMETER` will be replaced by `window.UNSAFE_ATL_CONTEXT_BOUNDARY` in
future iterations - see [go-is-fedramp](https://go.atlassian.com/is-fedramp).**

- `window.MICROS_PERIMETER` - see [go-is-fedramp](https://go.atlassian.com/is-fedramp) \*

### Server Generated HTML

_Recommended_

If your service always generates static HTML, you can leverage window context to correctly configure
this library. Consider this Velocity template snippet as an example:

```html
<!-- Assuming your Java service has loaded the appropriate configuration into $domain_config -->

<script nonce="$nonce">
	window.ATL_CONTEXT_DOMAIN = $domain_config.stringify();
</script>

<!-- Assuming your Java service has loaded the micros perimeter into $micros_perimeter.
    NOTE: Only needed if your service uses the isFedRamp function
  -->
<script nonce="nonce">
	window.UNSAFE_ATL_CONTEXT_BOUNDARY = $micros_perimeter.stringify();
</script>
```

The library will automatically initialise with this configuration if the variable is found. If the
config isn’t available it will use fallbacks and potentially return uncorrected values.

### Serverless

_Discourage: This will regress your apps performance. Your page is no longer serverless, due to its
requirement for FedRAMP config. You should move to server-based hosting._

Before render, you must fetch the data

```js
import { configure } from '@atlaskit/atlassian-context';

function init(){
  // get the config from globaledge
  const data = await fetch('https://my.backend.api/_config/domains');

  // tell @atlaskit/atlassian-context about it
  configure(data)

  // and only then run other code / render your page
  ReactDOM.render(<YourApp />, element)
}
```

If your application is rendered through React SSR, you should ensure you will need to manually
invoke the `configure()` function with the provided data.

## API

### configure()

_Disclaimer:_ This does not need to be invoked for the `isFedrampModerate()`, `isIsolatedCloud()`, `isolatedCloudDomain()`, `isolationContextId()`, `getDomainInContext(...)`, and `getUrlForDomainInContext(...)` functions.

Takes the data, and stores in `window.ATL_CONTEXT_DOMAIN` for later use.

### getATLContextDomain()


_Disclaimer:_ Please use `getDomainInContext(subdomain, environment)` instead of this function, as the deprecation process for this function will begin in the near future.

Returns the domain for a given Atlassian service. It relies on `window.ATL_CONTEXT_DOMAIN` be
present on the page, in case `window.ATL_CONTEXT_DOMAIN` is undefined `getATLContextDomain()` will
try to retrieve the value from a list of hardcoded domains, which could be not up to date. The
fallback relies on `window.UNSAFE_ATL_CONTEXT_BOUNDARY` be present on the page, if undefined
`getATLContextDomain()` will fallback to non-fedramp (commercial) value.

```js
import { getATLContextDomain } from '@atlaskit/atlassian-context';

getATLContextDomain('jira'); // jira.atlassian.com OR jira.atlassian-fex.com depending based on environment
getATLContextDomain('confluence'); // confluence.atlassian.com
getATLContextDomain('admin'); // admin.atlassian.com OR admin.atlassian-fex.com
```

### getATLContextUrl()


_Disclaimer:_ Please use `getUrlForDomainInContext(subdomain, environment)` instead of this function, as the deprecation process for this function will begin in the near future.

Returns the full `url` for a given Atlassian service. Being based off `getATLContextDomain`, it
relies on `window.ATL_CONTEXT_DOMAIN` be present on the page, otherwise `getATLContextDomain` will
try to retrieve the value from a list of hardcoded domains, which could be not up to date and
potentially fallback to non-fedramp (commercial) value.

`getATLContextUrl()` detects browser protocol (http/https) and applies it to `domain`.

```js
import { getATLContextUrl } from '@atlaskit/atlassian-context';

getATLContextUrl('jira'); // https://jira.atlassian.com OR https://jira.atlassian-fex.com depending based on environment
getATLContextUrl('confluence'); // https://confluence.atlassian.com
getATLContextUrl('admin'); // https://admin.atlassian.com OR https://admin.atlassian-fex.com
```

### isFedRamp()

_Disclaimer:_ Please use `isFedrampModerate()` instead of this function, as the deprecation process for this function will begin in the near future.

_Caution: Consider Alternatives_ Use of this function is not recommended as a long term solution, as
it creates an assumption there are no other isolated environments than just FedRAMP Moderate. You
are encouraged to consider alternate solutions, such as Statsig or environment configuration, that
don’t require creating a hard dependency between your code features and the FedRAMP environment -
see [go-is-fedramp](https://go.atlassian.com/is-fedramp)

Returns whether the service is deployed in the FedRAMP boundary. `isFedRamp()` relies on
`window.UNSAFE_ATL_CONTEXT_BOUNDARY` be present on the page, in case
`window.UNSAFE_ATL_CONTEXT_BOUNDARY` is undefined it will try to identify the environment based on
the site domain, eventually fallback to false.

```js
import { isFedRamp } from '@atlaskit/atlassian-context';

if (isFedRamp()) {
	// your specific logic here
}
```


### isFedrampModerate()
Returns true if the current perimeter is in FedRAMP-Moderate. 

### isIsolatedCloud()
Returns true if the current perimeter is in Isolated Cloud. 

### isolatedCloudDomain()
Returns the current `ic_domain`. If the current perimeter is not an L2 IC (ex. the current fedramp-moderate or regular commercial), then undefined is returned.


### isolationContextId()
Returns the current isolation context identifier (ex: `ic-123`). If the current perimeter is not an L2 IC (such as if the perimeter is fedramp-moderate or regular commercial), then undefined is returned.



### getDomainInContext(subdomain, environment)
Returns the full domain (including support for Isolation Cloud) for a given Atlassian service or experience. 

Important: Note that the library currently does NOT guarantee that the requested domain exists! It is assumed that when a user requests the full domain for a specific service, they already know the domain exists.


Parameters:

* `subdomain` is a required parameter. This should be the service or Atlassian experience for which the full domain is being requested.

* `environment` is a required parameter. This should be one of `dev`, `staging`, or `prod`.


#### Non-Isolated Cloud Details:

For Non-Isolated Cloud (ex. fedramp-moderate and regular commercial), the perimeter and environment values will be used to create and return the expected domain.

Exceptions to this are stored in the [fullDomainOverride](./src/common/constants/domains.tsx) definitions. If you require a URL Mapping that is inconsistent between perimeters and environments, then you should add an entry to `domains.tsx`.

Examples:
When called in fedramp-moderate:

```js
import { getDomainInContext } from '@atlaskit/atlassian-context';

getDomainInContext('id', 'staging') // returns "id.stg.atlassian-us-gov-mod.com" (id has a full domain override)
getDomainInContext('analytics', 'staging') // returns "analytics.atlassian.com" because `analytics` is a non-varying global domain
getDomainInContext('nonexistent-service', 'staging') // returns "nonexistent-service.stg.atlassian-us-gov-mod.com"
```

When called in (non-isolated) commercial:

```js
import { getDomainInContext } from '@atlaskit/atlassian-context';

getDomainInContext('id', 'prod') // returns "id.atlassian.com"
getDomainInContext('analytics', 'prod') // returns "analytics.atlassian.com"
```



#### Isolated Cloud Details:

For Oasis, one of three domain types are returned: a Reserved Name domain, a namespace subdomain, or an Atlassian services subdomain (see [RFC](https://hello.atlassian.net/wiki/spaces/NSC/pages/4352719139/RFC-3+Oasis+Isolation+Context+External+Public+DNS#Atlassian-owned-base-domain-with-domain-based-routing)).

Reserved names and the namespace subdomains are temporarily being configured in the [ReservedNameMapping and AtlDomainMapping](./src/services/generalized-domain-lookup/constants.tsx) definitions. If a new name has been registered under one of these categories, please raise a PR to update the relevant mapping.

Precedence is as follows: reserved name pattern > namespace pattern > default to the services pattern.

Example:
When called in (isolated) commercial:

```js
import { getDomainInContext } from '@atlaskit/atlassian-context';

getDomainInContext('id') // returns "id.<icLabel>.<baseDomain>"
getDomainInContext('packages') // returns "packages.atl.<icLabel>.<baseDomain>"
getDomainInContext('new-service') // returns "new-service.services.<icLabel>.<baseDomain>"
```

### getUrlForDomainInContext(subdomain, environment)
Returns the full url a given Atlassian service (including support for Isolation Cloud) by appending the current URL scheme to the result of `getDomainInContext(subdomain, environment)`.

```js
import { getUrlForDomainInContext } from '@atlaskit/atlassian-context';

getUrlForDomainInContext('design', 'staging') // --> returns "https://design.atlassian.com"
```

### resolveProvidedUrlByBoundary(urls)
Given a user-provided map of boundary keys to URLs, returns the URL associated with the current boundary. Unlike `getUrlForDomainInContext(subdomain, environment)`, which constructs a URL from a known Atlassian subdomain pattern, `resolveProvidedUrlByBoundary` is intended for cases where you have fully-formed, arbitrary URLs that may completely differ per boundary (for example, third-party service endpoints or custom backend URLs).

The only parameter is `urls`, a map of boundary keys to `URL` objects. The `default` key is **required** as a guaranteed fallback; all boundary-specific keys are optional.
Valid keys are `'isolated-cloud'` | `'fedramp-moderate'` | `'commercial'` | `'default'` (required)

Resolution order:

1. Specific boundary key (`'isolated-cloud'`, `'fedramp-moderate'`, or `'commercial'`)

2. `'default'`

Pass `null` for a boundary key to explicitly return `null` for that boundary (i.e. opt out of returning a URL).

> **Note:** URL values are constructed by the caller using `new URL(...)`. Passing an invalid URL string to `new URL()` will throw a `TypeError` before `resolveProvidedUrlByBoundary` is invoked.

```js
import { resolveProvidedUrlByBoundary } from '@atlaskit/atlassian-context/resolve-provided-url-by-boundary';

const url = resolveProvidedUrlByBoundary({
  'isolated-cloud':   new URL('https://ic.example.com'),  // returned in Isolated Cloud
  'fedramp-moderate': null,                                // explicitly no URL in FedRAMP to represent FedRAMP unavailability
  default:            new URL('https://example.com'),      // returned in all other boundaries
});
```

---
_Source: https://npm.io/package/@atlaskit/atlassian-context · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._