UNPKG

5.47 kBMarkdownView Raw
1# Bluesky Comments
2
3Embed Bluesky comments on your website easily.
4
5**[Write up and demo here](https://coryzue.com/writing/bluesky-comments).**
6
7
8## Installation via CDNs (easiest)
9
10There are a few ways to set up the library on your website.
11
12### 1. Add the CSS files
13
14Add the default styles the page `<head>` somewhere in a base template:
15
16```html
17<link rel="stylesheet" href="https://unpkg.com/bluesky-comments@<VERSION>/dist/bluesky-comments.css">
18```
19
20### 2. Add source maps for React
21
22Add the following importmap to your page anywhere before you use the library:
23
24```
25<script type="importmap">
26{
27 "imports": {
28 "react": "https://esm.sh/react@18",
29 "react-dom": "https://esm.sh/react-dom@18"
30 }
31}
32</script>
33```
34
35### 3. Import and use the library and any other functions you need in an ES module script:
36
37```html
38<script type="module">
39 import BlueskyComments from 'https://unpkg.com/bluesky-comments@0.4.0/dist/bluesky-comments.es.js';
40 document.addEventListener('DOMContentLoaded', function() {
41 const author = 'you.bsky.social';
42 if (author) {
43 BlueskyComments.init('bluesky-comments', {author});
44 }
45 });
46</script>
47```
48
49See the [Usage](#usage) section for details on the API.
50
51### (Deprecated) Installation using `<script>` tags and UMD
52
53Previous versions of this library recommended installing like this:
54
55```html
56<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
57<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
58<script src="https://unpkg.com/bluesky-comments@<VERSION>/dist/bluesky-comments.umd.js"></script>
59```
60
61And initializing the comments in a standard `<script>` tag. Both of these approaches work:
62
63```html
64<script>
65 document.addEventListener('DOMContentLoaded', function() {
66 const uri = 'https://bsky.social/coryzue.com/posts/3jxgux';
67 if (uri) {
68 // New API
69 BlueskyComments.init('bluesky-comments', {uri});
70
71 // Legacy API (still supported but deprecated)
72 initBlueskyComments('bluesky-comments', {uri});
73 }
74 });
75</script>
76```
77
78This option is now deprecated with the introduction of ES modules and will be removed in a future version.
79
80## Usage
81
82### Initializing the library based on the author
83
84```javascript
85const author = 'you.bsky.social';
86BlueskyComments.init('bluesky-comments', {author});
87```
88
89If you use this mode, the comments section will use the most popular post by that author that links
90to the current page.
91
92### Initializing the library based on a post URL
93
94```javascript
95const uri = 'https://bsky.social/coryzue.com/posts/3jxgux';
96BlueskyComments.init('bluesky-comments', {uri});
97```
98
99If you use this mode, the comments section will use the exact post you specify.
100This usually means you have to add the comments section only *after* you've linked to the article.
101
102
103### (Advanced) Providing custom default empty states
104
105You can pass in a `onEmpty` callback to handle the case where there are no comments rendered
106(for example, if no post matching the URL is found or there aren't any comments on it yet):
107
108```javascript
109BlueskyComments.init('bluesky-comments', {
110 uri,
111 author,
112 onEmpty: (details) => {
113 console.error('Failed to load comments:', details);
114 document.getElementById('bluesky-comments').innerHTML =
115 'No comments on this post yet. Details: ' + details.message;
116 },
117});
118```
119
120### (Advanced) Filtering comments
121
122You can pass in an array of filters to the `commentFilters` option. These are functions that take a comment and return a boolean. If any of the filters return true, the comment will not be shown.
123
124A few default filters utilities are provided:
125
126- `BlueskyComments.Filters.NoPins`: Hide comments that are just "📌"
127- `BlueskyComments.Filters.NoLikes`: Hide comments with no likes
128
129You can also use the following utilities to create your own filters:
130
131- `BlueskyComments.Filters.MinLikeCountFilter`: Hide comments with less than a given number of likes
132- `BlueskyComments.Filters.MinCharacterCountFilter`: Hide comments with less than a given number of characters
133- `BlueskyComments.Filters.TextContainsFilter`: Hide comments that contain specific text (case insensitive)
134- `BlueskyComments.Filters.ExactMatchFilter`: Hide comments that match text exactly (case insensitive)
135
136Pass filters using the `commentFilters` option:
137
138```javascript
139BlueskyComments.init('bluesky-comments', {
140 // other options here
141 commentFilters: [
142 BlueskyComments.Filters.NoPins, // Hide pinned comments
143 BlueskyComments.Filters.MinCharacterCountFilter(10), // Hide comments with less than 10 characters
144 ],
145});
146```
147
148You can also write your own filters, by returning `true` for comments you want to hide:
149
150```javascript
151const NoTwitterLinksFilter = (comment) => {
152 return (comment.post.record.text.includes('https://x.com/') || comment.post.record.text.includes('https://twitter.com/'));
153}
154BlueskyComments.init('bluesky-comments', {
155 // other options here
156 commentFilters: [
157 NoTwitterLinksFilter,
158 ]
159});
160```
161
162## Installation with npm
163
164```bash
165npm install bluesky-comments
166```
167
168I don't publish a lot of JavaScript packages, but I think you can import it by doing this!
169
170
171## Development
172
173To develop on this package, you can run:
174
175```
176npm install
177npm run watch
178```
179
180This will watch for changes and copy the built files to the `dist` directory.
181From there you can reference the files in your own project and any updates you make
182should show up instantly.