Skip to content

✨ Show experimental APIs on the API docs#1205

Merged
taras merged 1 commit into
v4from
tm/1200-experimental-badge
Jul 6, 2026
Merged

✨ Show experimental APIs on the API docs#1205
taras merged 1 commit into
v4from
tm/1200-experimental-badge

Conversation

@taras

@taras taras commented Jul 5, 2026

Copy link
Copy Markdown
Member

Motivation

Closes #1200.

We're adding experimental APIs in 4.1, but we don't currently have a way to show experimental APIs on the website.

Approach

  1. useDenoDoc includes experimental flag which is added for symbols that are exported from ./experimental package export
  2. added a route that shows experimental symbols at `/api/${s.name}/experimental/:symbol``
  3. list pages now takes groups of symbols to show which includes experimental and default export
  4. showing a banner on experimental routes
image image

@pkg-pr-new

pkg-pr-new Bot commented Jul 5, 2026

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/effection@1205

commit: c0766ef

@codspeed-hq

codspeed-hq Bot commented Jul 5, 2026

Copy link
Copy Markdown

Merging this PR will improve performance by 11.32%

⚡ 1 improved benchmark
✅ 5 untouched benchmarks

Performance Changes

Mode Benchmark BASE HEAD Efficiency
Memory effection-inline.recursion 3.7 KB 3.3 KB +11.32%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.


Comparing tm/1200-experimental-badge (c0766ef) with v4 (4f400d0)

Open in CodSpeed

@cowboyd

cowboyd commented Jul 6, 2026

Copy link
Copy Markdown
Member

One thing I noticed is that it is using the JSR name for the endpoint "@effection/effection/experimental"

But for consumers from NPM, and honestly, consumers from JSR that use an import map to map @effection/effection -> effection will see this in code as `import { createApi } from "effection/experimental"

Surface symbols exported from the package's `./experimental` entrypoint in the
API Reference section:

- `/api` index lists a stable release's experimental symbols inline with an
  "experimental" badge (none for 4.0.3 today; appears when a stable release
  exports `./experimental`). The prerelease's experimental APIs are reached via
  the "next" toggle / its symbol pages.
- Experimental symbol pages live at `/api/:series/experimental/:symbol` with an
  "Experimental" banner; the sidebar lists stable + experimental symbols with
  badges, resolving each link to the correct (flat vs namespaced) URL.
- Version toggle gains a "next" entry for the prerelease when it's newer than
  its stable parent and documents the current symbol.

The "experimental" signal is entrypoint membership (`DocPage.experimental`, set
in `package.ts`). The series is read from the request (`useApiSeries`) rather
than threaded as a prop. Stable pages, older series, and search are unaffected.
@taras taras force-pushed the tm/1200-experimental-badge branch from 285cbaa to c0766ef Compare July 6, 2026 12:11
@taras

taras commented Jul 6, 2026

Copy link
Copy Markdown
Member Author

Good catch — fixed in c0766ef. The experimental banner now reads effection/experimental (the npm name / import-map form) instead of the JSR-scoped @effection/effection/experimental, matching what consumers actually write in an import.

@taras taras merged commit 4380c5f into v4 Jul 6, 2026
19 checks passed
@taras taras deleted the tm/1200-experimental-badge branch July 6, 2026 17:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Show Experimental APIs on the apidocs

2 participants