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

Add Bun section to Getting started #2517

Merged
merged 6 commits into from
Jul 23, 2024
Merged

Add Bun section to Getting started #2517

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
351f170
Add short Bun section to end of `@mdx-js/esbuild` section
karlhorky Jul 22, 2024
f188aa9
Address feedback points
karlhorky Jul 22, 2024
474a248
Update docs/docs/getting-started.mdx
karlhorky Jul 23, 2024
cacb627
Update docs/docs/getting-started.mdx
karlhorky Jul 23, 2024
51354dc
Update docs/docs/getting-started.mdx
karlhorky Jul 23, 2024
3de41ee
Update filename
karlhorky Jul 23, 2024
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
30 changes: 29 additions & 1 deletion docs/docs/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ MDX is a language that’s compiled to JavaScript.
The easiest way to get started is to use an integration for your bundler if you
have one:

* if you use **esbuild**,
* if you use **esbuild** (or Bun),
install and configure [`@mdx-js/esbuild`][mdx-esbuild]
* if you use **Rollup** (or Vite),
install and configure [`@mdx-js/rollup`][mdx-rollup]
Expand Down Expand Up @@ -234,6 +234,10 @@ etc.) you use.
To use more modern JavaScript features than what your users support,
[configure esbuild’s `target`][esbuild-target].

See also [¶ Bun][javascript-engines-bun],
which you might be using,
for more info.

#### Rollup

<details>
Expand Down Expand Up @@ -798,6 +802,26 @@ MDX files can be imported in Node by using
[`@mdx-js/node-loader`][mdx-node-loader].
See its readme on how to configure it.

#### Bun

MDX files can be imported in [Bun][] by using
[`@mdx-js/esbuild`][mdx-esbuild].

<details>
<summary>Expand example</summary>

```toml path="bunfig.toml"
preload = ["./bunMdxEsbuild.ts"]
```

```js twoslash path="bunMdxEsbuild.ts"
Copy link
Member

Choose a reason for hiding this comment

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

One thing I wonder about is this casing in the filename? Is this a very strong recommendation by bun, to use camelcasing? Seems like that would fail on some file systems?

Should the name include esbuild, or is that a side effect of what the focus is: Bun + MDX?

How about a short:

Suggested change
preload = ["./bunMdxEsbuild.ts"]
```
```js twoslash path="bunMdxEsbuild.ts"
preload = ["./mdx.ts"]
```
```js twoslash path="mdx.ts"

Copy link
Member

Choose a reason for hiding this comment

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

bun-preload.ts also seems viable?

Copy link
Contributor Author

@karlhorky karlhorky Jul 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Is this a very strong recommendation by bun, to use camelcasing?

It was my own choice. Camel case in filenames are pretty common in JavaScript and TypeScript ecosystems. Seeing beginners work with camel case on a variety of operating systems, the errors that it causes are not very common and they can be warned against using ESLint and other tools. So I'm pretty pro-camel case I guess.

I think mdx.ts is not expressive enough. If it should be lowercase (kebab case?) then at least bun-mdx.ts or bun-mdx-plugin.ts

Copy link
Member

@wooorm wooorm Jul 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

OK, I’m very 👎 on camelcase in filenames, I only sometimes see React people use it more recently. It’s not used anywhere in the things I work on.

Did you see my 2nd suggestion, bun-preload.ts?

My acceptable preferences in order are: bun-preload.ts, mdx.ts, bun.ts, bun-mdx.ts. All fine. They all answer “wait, why is this file here again?”. Can you choose which one you prefer?

I think the inclusion of “plugin” in bun-mdx-plugin.ts is unneeded. Similar to “esbuild” bunMdxEsbuild.ts. These terms have to do with how that file currently works internally.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok, switched to bun-mdx.ts in 3de41ee

import {plugin} from 'bun'
import mdx from '@mdx-js/esbuild'

plugin(mdx())
```
</details>

## Further reading

* If you want to use MDX content in your project,
Expand Down Expand Up @@ -911,6 +935,10 @@ See its readme on how to configure it.

[build-system-vite]: #vite

[bun]: https://bun.sh

[javascript-engines-bun]: #bun

[bundler-esbuild]: #esbuild

[bundler-rollup]: #rollup
Expand Down