[EDU-1845] Pub/Sub getting started in JavaScript #2511
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Looks great, couple small comments.
There is no error handling or graceful teardown logic in this example. I do think that might be an important thing for users to be made aware of early on in their experimentation - equally I can see the desire to keep this lean. What do you think?
I have a question about how we intend to approach the JS/TS ecosystems with these guides - not something that needs to block this PR, but I do think we need to solve this more generally:
- Will we have typescript equivalents?
- More generally, how do we intend to manage JS vs TS in all code examples throughout the docs? Of course they are both AblyJS, but the usage examples will differ. Should we have a TS option in the language selector dropdown?
- How to we handle running code snippets for JS/TS via Node vs the browser?
- Some of the setup steps may differ, e.g. use
ts-nodevs use webpack vs include a script tag in anindex.html, etc. How do other companies solve this problem in their guides?
- Some of the setup steps may differ, e.g. use
| * Run the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use token authentication in a production app. A @clientId@ ensures the client is identified, which is required to use certain features, such as presence: | ||
|
|
||
| ```[javascript] | ||
| import * as Ably from 'ably'; |
There was a problem hiding this comment.
This syntax will only work if you specify "type": "module" in the package.json, and we haven't told the reader to do that
| * Install the Ably CLI: @npm install -g @ably/cli@ | ||
| * Run @ably login@ in the terminal and follow the prompts to provide an access token to the Ably CLI. | ||
| * Set the default app to use with @ably apps switch@ and select an API key to use for operations with @ably auth keys switch@. | ||
| * Install the Ably Pub/Sub JavaScript SDK in a new project within your IDE: @npm install ably@ |
There was a problem hiding this comment.
Should we include a step to run npm init to create a package.json before installing deps?
There was a problem hiding this comment.
Updated prereq steps to make them clearer ce3a81d
| getStarted(); | ||
| ``` | ||
|
|
||
| You can monitor the lifecycle of clients' connections, but for now just log a message to the console to know that the connection attempt was successful. You'll see the message printed to your console, and you can also inspect the connection event in the dev console of your app. |
There was a problem hiding this comment.
You can monitor the lifecycle of clients' connections
How?
There was a problem hiding this comment.
Updated to explain this without going into too much detail ce3a81d
|
|
||
| * Open up the "dev console":https://ably.com/accounts/any/apps/any/console of your first app before instantiating your client so that you can see what happens. | ||
|
|
||
| * Run the following function to instantiate the SDK and establish a connection to Ably. At the minimum you need to provide an authentication mechanism. Use an API key for simplicity, but you should use token authentication in a production app. A @clientId@ ensures the client is identified, which is required to use certain features, such as presence: |
There was a problem hiding this comment.
Create an index.js file with the following contents and run it with node index.js
| * Join and subscribe to the presence set of the channel. | ||
| * Retrieve the messages you sent in the guide from history. | ||
|
|
||
| h2(#prerequisites). Prerequisites |
There was a problem hiding this comment.
Missing Node.js installation?
|
|
||
| ```[javascript] | ||
| const history = await channel.history(); | ||
| console.log(history.items.map((message) => message.data)); |
|
|
||
| ```[json] | ||
| [ | ||
| 'Message number 1', |
There was a problem hiding this comment.
History responses are returned in reverse chronological order by default (newest first), so this would actually be 5, 4, 3, 2, 1
| console.log(`Event type: ${member.action} from ${member.clientId} with the data ${JSON.stringify(member.data)}`) | ||
| }); | ||
|
|
||
| await channel.presence.enter("I'm here!"); |
There was a problem hiding this comment.
I think using a string here but JSON in the CLI is confusing, we should just use a string in each case (I think data that says status = online is redundant, because if you're offline you won't be in the presence set, so there is not really a case where you have entered status = offline in the member data)
There was a problem hiding this comment.
I agree, however it seems the CLI currently only takes a JSON object for data. I've updated the text away from "online" whilst we fix the CLI.
Thanks Mike.
|
Description
This PR adds a new getting started guide for Ably Pub/Sub in JavaScript.
It includes;
h2,olandulelements for readability in the getting started guide.Checklist