Skip to content

feat(docs): Add docs for Share Playground session #69

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.

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

Merged
merged 10 commits into from
May 12, 2025
72 changes: 72 additions & 0 deletions docs/studio/playground/shared-playground-state.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
---
title: "Sharing Playground Sessions"
description: "You can now share your Cosmo Playground session with others using a single URL. This feature enables easier collaboration and debugging across your team — no need to copy and paste queries or configurations manually."
---

## What's Included in the Share Link?

When creating a shareable link, you can **choose which parts** of your Playground session to include.

Here's what you can share:

| Option | Shareable? | Required | Notes |
| :---------------- | :--------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GraphQL Operation | Always | Yes | Always included by default. Cannot be deselected. |
| Variables | If present | No | Included only when content is available and the option is selected. If no content is present, the option appears disabled under "No content available to share. Add content to enable sharing these options." To enable it, add relevant content in the Playground. |
| Headers | If present | No | Included only when content is available and the option is selected. If no content is present, the option appears disabled under "No content available to share. Add content to enable sharing these options." To enable it, add relevant content in the Playground. |

<Note>
The GraphQL Operation could be a query, mutation or subscription
</Note>

## How to Share a Session?

<iframe src="https://www.loom.com/embed/76b9d1e51ecd4481a334daaaba145f0c?sid=e8104713-5cff-466c-b898-5c4ec1d892f5" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen width="100%" height="400" ></iframe>
Copy link
Contributor

Choose a reason for hiding this comment

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

I really like the video here!


<Steps>
<Step title="Open the Playground and compose your GraphQL operation">

</Step>
<Step title="Add any variables or headers you’d like to include">

</Step>
<Step title="Click Share icon with the tooltip “Share Playground State” in the toolbar">

</Step>
<Step title="A modal will appear with options to choose:">
- Available options will appear in top section
- Unavailable options (if no content available) will appear in the bottom section
</Step>
<Step title="Select the available options you want to include in the shared link">

</Step>
<Step title='Click "Copy link" to generate and copy the shareable URL'>

</Step>
</Steps>

## Opening a Shared Link

Recipients of a shared link will see the shared Playground session in a new tab with:

- The **operation** restored exactly as composed
- Optional **variables** and **headers** if they were included

## Not Included in Shared Links

The following are never included in the shared link:

- Pre-flight scripts
- Pre-operation scripts
- Post-operation scripts

## Security Considerations

If you choose to include headers, they are compressed and encoded as part of the generated URL. While the data is not human-readable, it is accessible to anyone who has the link. For your safety, avoid including sensitive data such as API tokens or credentials in shared headers.

## Use Cases

- Share reproducible bugs with your team
- Collaborate on queries with full context
- Link to example queries in internal docs
- Speed up onboarding of new developers with pre-filled queries