EDU 1889: Improve Pub/Sub JavaScript Readme

[franrob-projects]

This PR streamlines and refocuses the content of README.md to improve readability, simplify navigation, and make ongoing maintenance easier.

Commits

EDU-1957: Rewrites introduction and overview

Replaces marketing-heavy intro with a concise overview of the Ably Pub/Sub SDK.

EDU-1889: Rewrites supported platforms section

Reorganizes platform support information into a clearer, more concise format. Merges browser compatibility support into a table.

EDU-1889: Adds getting started

Introduces a new "Getting Started" section with quick links for JavaScript, React, and LiveObjects.

EDU-1889: Removed as covered in docs

Removes install content already maintained in docs.

EDU-1889: Condenses and moves Webpack instructions

• Simplifies Webpack setup steps. Consolidates browser and server usage and separates modular and default bundling.
• Note: Aware that server-side rendering for webpeck is not documented elsewhere.

EDU-1889: Moves Modular variant instructions

Relocates the modular variant details into its own section after install instructions.

EDU-1889: Removes outdated TypeScript and NativeScript examples

Removes legacy code blocks and GIF demos.

EDU-1889: Removes Realtime and REST API usage as covered in docs

Removes usage examples for Realtime and REST APIs to prevent (already present) drift from docs.

EDU-1889: Removes Push activation as covered in docs

Removes usage examples for Push to prevent drift from docs.

EDU-1889: Removes Live objects as covered in docs

• Removes LiveObjects content to prevent a future drift from docs.
• Link added under getting started to LiveObjects.

EDU-1889: Removes Delta plugin as covered in docs

• Removes Delta plugin as covered in docs.
• Potential ticket required to update Delta section in the docs

EDU-1889: Moves Contributing and removes Credits

• Moves the Contributing section further up the doc
• Removes unneeded

EDU-1889: Adds Releases section

Introduces a Releases section linking to CHANGELOG and changelog.ably.com for version history and upgrade notes.

EDU-1889: Condenses Support section

Streamlines troubleshooting info and adds direct links to help resources.

Notes:

• We have graphic headers in design to improve visuals (these will be rolled out across all SDKs).

• I have removed the following badges for now (I want to discuss keeping them if needed, removing permanently, or adding new ones):

Jira

https://ably.atlassian.net/browse/EDU-1889

Summary by CodeRabbit

• Documentation
  • Significantly revised the README for improved clarity and structure.
  • Updated platform support details and installation instructions.
  • Condensed API usage examples, replacing most with links to official documentation.
  • Enhanced guidance on development environment issues and compatibility notes.
  • Added clearer troubleshooting tips for common connection errors.

[coderabbitai[bot]]

Walkthrough

The README.md file for the Ably Pub/Sub JavaScript SDK was extensively revised. The update streamlines content, restructures sections for clarity, replaces detailed API usage examples with external documentation links, and adds updated notes on platform compatibility and development environment pitfalls. No code or public API declarations were changed.

Changes

File(s)	Change Summary
README.md	Major rewrite: improved structure and clarity, condensed installation and modular usage instructions, removed detailed API examples, added external documentation references, updated platform and support notes, clarified development pitfalls and solutions.

Assessment against linked issues

Objective	Addressed	Explanation
Create generic SDK README template (JS) (EDU-1889)	✅
Create / apply SDK template to Chat JS SDK (EDU-1957)	❌	No changes related to Chat JS SDK or its README template were made.

Possibly related PRs

• ably/ably-js#1905: Also updates README to address "connection limit exceeded" errors during development, overlapping with this PR’s new guidance.
• ably/ably-js#1969: Modifies the README’s LiveObjects section with detailed usage instructions, while this PR streamlines that section and refers to external docs.

Suggested reviewers

• Zariel

Poem

In README fields where docs once grew,
The rabbit prunes, and guides anew.
With links and notes, the path is clear,
No tangled code for us to fear!
Hop forth, dear devs, with docs concise—
The garden’s trimmed, the carrots nice! 🥕

✨ Finishing Touches

🧪 Generate unit tests

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch EDU-1889-Improve-Pub/Sub-JavaScript-README

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai auto-generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[franrob-projects]

• Visually, this seems like a bit of a downgrade compared to the previous version - the badges and emphasised text looked kind of nice. Admittedly it didn't look great before but now it's pretty much entirely plain unstyled text which I think looks a bit dull. Compare to something like https://github.com/vitejs/vite, which has a big logo, badges, quoted text and emojis right at the start - it looks a lot more flashy, and I think that's something that's worth pursuing.

• Graphic headers have been added here for visual appeal, as they have with all of the SDK repos
• Only relevant badges have been added. The same badges types have been applied to all of the SDK repos (version and license).

• I like how you've made collapsible sections for the modular variant docs! we should do the same for the support issues too (chrome extensions, etc)

• Collapsible sections have now been added to all longer pieces of info.

• The delta plugin is documented on the website but the documentation there is a bit lacking compared to what we have here - for example it doesn't say how to actually install the plugin. At a minimum we should update the website docs to link out to https://github.com/ably-forks/vcdiff-decoder#usage.

• The JS Delta docs have been updated with information referenced mainly in vcdiff-decoder documentation. The Delta section removed for this repo was not entirely different from what was already in the doc.

• The NPM badge is very common for javascript repos and I find quite useful as a quick way to get to the npmjs.com page for a package, so I would prefer to keep that. I'm happy to remove the features CI badge, but I think badges are generally nice looking and can be useful so I think removing them all seems like a bad idea to me.

• Only relevant badges have been added. The same badges types have been applied to all of the SDK repos (version and license).

• I am happy to remove the bulk of the usage examples from the README but I do think at a minimum we should have a simple installation section and some very basic usage snippets. Personally, I really hate having to go to a company website just to find the most basic API usage or what npm install command I need to run - we don't have to have every rest endpoint or whatever but just an npm install ably command and a simple pub/sub example here would be less annoying for developers like myself while also making the README more visually appealing.

• Adds refined installation and usage sections.

• The 'supported platforms' section I think could do with some more thought - most of the browser versions are very old, and the only build tool we mention is webpack (while most developers nowadays are using vite, esbuild, etc) so even if it's still true it kinda looks like we haven't updated it in years. I appreciate that this can be changed in a separate PR, but now seems like as good time to do it as ever 🙂 . Here I would suggest just advertising LTS support for web browsers, dropping any mentions of node 16 (we can still link to the package.json 'engines' field which mentions node 16 anyway), and reconsidering how we document usage with build tools. These build tools only really need to know what modules and ES version the package uses so if we document these then users can figure it out themselves and figure it out using the documentation for their build tools. @VeskeR @ttypic wdyt?

• On the supported platforms section, LTS support has been added to all browsers.
• For Node.js, >=16.x or later has been dropped.