Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update compatibility mode docs #1855

Merged
merged 5 commits into from
Feb 13, 2025
Merged

Update compatibility mode docs #1855

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
880579b
Update compatibility mode docs
heitortsergent Feb 7, 2025
7b167e9
Update docs/sources/k6/next/using-k6/javascript-typescript-compatibil…
heitortsergent Feb 10, 2025
daa9837
Move explanation about base/extended difference
heitortsergent Feb 10, 2025
157ddd1
Merge branch 'main' into hts/compatibility-mode
heitortsergent Feb 13, 2025
50526e3
Apply changes to v0.57.x
heitortsergent Feb 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 19 additions & 19 deletions docs/sources/k6/next/using-k6/javascript-typescript-compatibility-mode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,20 @@ weight: 19

# JavaScript compatibility mode

This is option most users should no longer be using.
{{< admonition type="note" >}}

In previous versions k6 used to not natively support as much of the ECMAScript standard as was desired. For this reason the default mode used to use babel internally to add support for what was missing. This though had performance impact on starting k6 and might still not have supported as much as was desired. As such a different mode without babel (and core.js) was added that was much faster in initialization, but likely required transpilation from the user.
If you're using k6 v0.53 or higher, the compatibility mode feature doesn't have much impact on the k6 default behavior. Refer to [this GitHub issue](https://github.com/grafana/k6/issues/3864) for more details.

Since v0.53.0 this hasn't been needed and in general this option has minimal usability and is likely to be removed completely in future versions. See [issue](https://github.com/grafana/k6/issues/3864) for the last remaining difference.
Starting on k6 v0.57, TypeScript support is enabled by default, and the `experimental-enhanced-mode` option has been removed.

Additionally, k6 also has support for [esbuild](https://esbuild.github.io/), to transpile TypeScript (TS) code. This used to use compatibility-mode but is now enabled by default and no configuration is required.
{{< /admonition >}}

Some users prefer to bundle their test code outside k6. For this reason, k6 offers three JavaScript compatibility modes:
k6 offers two JavaScript compatibility modes:

- [Extended mode](#extended-mode): The default option. That is `base` + aliasing `global` to `globalThis` - a nodejs compatibility.
- [Base mode](#base-mode): Only using native support in k6 and the underlying JS engine. After v0.53.0 it has the same functionality as `extended` apart from the `global` aliasing.
- [Base mode](#base-mode): Only uses native support in k6 and the underlying JavaScript runtime. For k6 v0.53.0 or higher, it has the same functionality as `extended` apart from the `global` aliasing.
- [Extended mode](#extended-mode): Similar to base mode, with an additional alias from `global` to `globalThis` for Node.js compatibility. This is the default mode.

After k6 v0.53.0, the only difference between the base and extended modes is that `global`, the Node.js global variable, is aliased to the value of `globalThis`.
Comment on lines +20 to +25
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@codebien do you think this is better? I'm wondering if it's a little repetitive. 🤔

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My suggestion was to have it early but in a single place. I think it is useful to have this additional context already before starting to read the list. Except if we put it directly on the specific item. But still, it should be only once in total.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it. I think I'm gonna leave it as is then, there is some repetition but I don't think it's necessarily bad. And we should be able to hide/delete this page in the near future.


When running tests, you can change the mode by using the `--compatibility-mode` option:

Expand All @@ -40,40 +42,38 @@ $ k6 run script.js

{{< /code >}}

After v0.53.0 the only difference with base is that `global` (node's global variable) is aliased to the value of `globalThis`.

## Typescript support
## Base mode

{{< code >}}

```cli
$ k6 run script.ts
$ k6 run --compatibility-mode=base script.js
```

```env
$ k6 run script.ts
$ K6_COMPATIBILITY_MODE=base k6 run script.js
```

{{< /code >}}

It uses [esbuild](https://esbuild.github.io/) to transpile TypeScript (TS) code for all files that have the `.ts` extension.

TypeScript support is partial as it strips the type information but doesn't provide type safety.

## Base mode
## Typescript support

{{< code >}}

```cli
$ k6 run --compatibility-mode=base script.js
$ k6 run script.ts
```

```env
$ K6_COMPATIBILITY_MODE=base k6 run script.js
$ k6 run script.ts
```

{{< /code >}}

k6 uses [esbuild](https://esbuild.github.io/) to transpile TypeScript (TS) code for all files that have the `.ts` extension.

TypeScript support is partial as it strips the type information but doesn't provide type safety.

### CommonJS Example

{{< code >}}
Expand Down
38 changes: 19 additions & 19 deletions docs/sources/k6/v0.57.x/using-k6/javascript-typescript-compatibility-mode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,20 @@ weight: 19

# JavaScript compatibility mode

This is option most users should no longer be using.
{{< admonition type="note" >}}

In previous versions k6 used to not natively support as much of the ECMAScript standard as was desired. For this reason the default mode used to use babel internally to add support for what was missing. This though had performance impact on starting k6 and might still not have supported as much as was desired. As such a different mode without babel (and core.js) was added that was much faster in initialization, but likely required transpilation from the user.
If you're using k6 v0.53 or higher, the compatibility mode feature doesn't have much impact on the k6 default behavior. Refer to [this GitHub issue](https://github.com/grafana/k6/issues/3864) for more details.

Since v0.53.0 this hasn't been needed and in general this option has minimal usability and is likely to be removed completely in future versions. See [issue](https://github.com/grafana/k6/issues/3864) for the last remaining difference.
Starting on k6 v0.57, TypeScript support is enabled by default, and the `experimental-enhanced-mode` option has been removed.

Additionally, k6 also has support for [esbuild](https://esbuild.github.io/), to transpile TypeScript (TS) code. This used to use compatibility-mode but is now enabled by default and no configuration is required.
{{< /admonition >}}

Some users prefer to bundle their test code outside k6. For this reason, k6 offers three JavaScript compatibility modes:
k6 offers two JavaScript compatibility modes:

- [Extended mode](#extended-mode): The default option. That is `base` + aliasing `global` to `globalThis` - a nodejs compatibility.
- [Base mode](#base-mode): Only using native support in k6 and the underlying JS engine. After v0.53.0 it has the same functionality as `extended` apart from the `global` aliasing.
- [Base mode](#base-mode): Only uses native support in k6 and the underlying JavaScript runtime. For k6 v0.53.0 or higher, it has the same functionality as `extended` apart from the `global` aliasing.
- [Extended mode](#extended-mode): Similar to base mode, with an additional alias from `global` to `globalThis` for Node.js compatibility. This is the default mode.

After k6 v0.53.0, the only difference between the base and extended modes is that `global`, the Node.js global variable, is aliased to the value of `globalThis`.

When running tests, you can change the mode by using the `--compatibility-mode` option:

Expand All @@ -40,40 +42,38 @@ $ k6 run script.js

{{< /code >}}

After v0.53.0 the only difference with base is that `global` (node's global variable) is aliased to the value of `globalThis`.

## Typescript support
## Base mode

{{< code >}}

```cli
$ k6 run script.ts
$ k6 run --compatibility-mode=base script.js
```

```env
$ k6 run script.ts
$ K6_COMPATIBILITY_MODE=base k6 run script.js
```

{{< /code >}}

It uses [esbuild](https://esbuild.github.io/) to transpile TypeScript (TS) code for all files that have the `.ts` extension.

TypeScript support is partial as it strips the type information but doesn't provide type safety.

## Base mode
## Typescript support

{{< code >}}

```cli
$ k6 run --compatibility-mode=base script.js
$ k6 run script.ts
```

```env
$ K6_COMPATIBILITY_MODE=base k6 run script.js
$ k6 run script.ts
```

{{< /code >}}

k6 uses [esbuild](https://esbuild.github.io/) to transpile TypeScript (TS) code for all files that have the `.ts` extension.

TypeScript support is partial as it strips the type information but doesn't provide type safety.

### CommonJS Example

{{< code >}}
Expand Down