<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Arek Nawo on Medium]]></title>
        <description><![CDATA[Stories by Arek Nawo on Medium]]></description>
        <link>https://medium.com/@areknawo?source=rss-703e187f4ea2------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*ctfm74Ps3AOGwJ3i3s09Ew.png</url>
            <title>Stories by Arek Nawo on Medium</title>
            <link>https://medium.com/@areknawo?source=rss-703e187f4ea2------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 06:09:38 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@areknawo/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[WYSIWYG for MDX?! Introducing Vrite’s Hybrid Editor]]></title>
            <link>https://areknawo.medium.com/wysiwyg-for-mdx-introducing-vrites-hybrid-editor-26f2fe7372e8?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/26f2fe7372e8</guid>
            <category><![CDATA[webdev]]></category>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[open-source]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Wed, 18 Oct 2023 16:02:03 GMT</pubDate>
            <atom:updated>2023-10-18T16:02:03.370Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*8aGSENaWoFNAPvfl.png" /></figure><p>You might be familiar with so-called <em>What You See Is What You Get</em> (WYSIWYG) or <em>Rich Text</em> editors. They’re the core part of popular apps such as Notion, allowing users to both see and edit the formatting and content of the document.</p><p>WYSIWYG editors are great for creating all kinds of content but, in some cases, they might be limiting, allowing you to use only a small set of formatting options and elements supported by the editor.</p><p>That’s especially problematic in niche content categories, like technical/<strong>developer content</strong>, where content requirements might differ, between companies, teams, and even individual projects.</p><p>That’s why formats like <strong>Markdown</strong> (MD) and <a href="https://mdxjs.com/">MDX</a> (MD with support for JSX) are so popular for use cases like documentation, knowledge bases, or technical blogs. They allow you to use any kind of custom formatting or elements and then process the content for publishing. On top of that, they’re great for implementing a <strong>docs-as-code</strong> approach, where your documentation lives right beside your code (i.e. in a Git repo).</p><p>However, writing Markdown files is a very different experience compared to the WYSIWYG approach. It can be challenging for beginners or less technical users, while also getting increasingly difficult to manage as the content base grows. My latest project — <a href="https://vrite.io/">Vrite</a> — is meant to solve this problem.</p><h3>Vrite Hybrid Editor</h3><p>Vrite is an <a href="https://github.com/vriteio/vrite/stargazers">open-source</a> developer content platform, featuring extensible editing experience, content management tools, and powerful APIs. It’s intended as an all-in-one, collaborative solution for product documentation, technical blogs, and knowledge bases.</p><p>With a collaborative WYSIWYG editor being a core part of the experience, I was <a href="https://x.com/areknawo/status/1703836534586151017">thinking for a long time</a> about how to create an experience that still has the power and customizability of MDX when needed. That’s how I came up with Vrite’s new <a href="https://editor.vrite.io/"><em>Hybrid Editor</em></a>.</p><figure><img alt="The Element block in Vrite editor" src="https://cdn-images-1.medium.com/proxy/0*AcWxlUjNnNOgAQeU" /></figure><p>To be fair, rather than being a whole new editor, in the latest v0.3, the Vrite editor was slightly redesigned and got a new block content type — <em>Element</em> — which enables the use of JSX-like blocks right in the editor, leading to a part-markup, part-WYSIWYG editor.</p><p>The Element block can have a <em>type</em> (e.g. Card) and a set of <em>props</em> (like title or options). You can edit it by clicking the opening tag. When the block is active and editable, its syntax will be highlighted.</p><figure><img alt="Editing Element block in Vrite editor" src="https://cdn-images-1.medium.com/proxy/0*QqnGP9pgrvhkESPI" /></figure><p>Elements can be either wrappers (containing content) or simple block nodes. You can switch between those two “modes”, similar to how it’s done in JSX/MDX — by changing the closing bracket of the first tag. /&gt; is for self-closing, while &gt; — for wrapping.</p><p>Behind the scenes, Vrite processes the content and makes it accessible in <a href="https://prosemirror.net/">ProseMirror-based</a> JSON format, including the type and all the props of the Element block.</p><figure><img alt="JSON content from the Element block." src="https://cdn-images-1.medium.com/max/1024/0*EJncCp7MYCAtpgoh.png" /></figure><p>This format makes it easy to further process the content — whether that’s for use with other features of Vrite or when accessing it through the API for publishing.</p><h3>MDX and GitHub Sync</h3><p>With the Element block enabling the use of more custom content, it also empowers other features of Vrite — such as <strong>Git sync</strong> — with new possibilities.</p><h4>Git Sync</h4><p>When your existing documentation or technical content is stored in MD files in your Git repo, or you want to implement a docs-as-code approach, with your repo being the <em>single source of truth</em> — Git sync allows you to sync the content from your repo with Vrite.</p><figure><img alt="Vrite Git sync - resolving conflicts" src="https://cdn-images-1.medium.com/max/1024/0*nbVwQ0ce86ImChc0.png" /></figure><p>This way you can still use all of Vrite’s features (e.g. content management, publishing extensions, semantic search, etc.), while also being able to commit your changes to the repo, resolve conflicts, etc. Basically, Git sync turns Vrite into a technical content editor, with additional features on top.</p><p>Currently (v0.3.2), Git sync only integrates with <strong>GitHub</strong>, with other providers planned for later on.</p><figure><img alt="Configuring Vrite&#39;s Git sync with GitHub" src="https://cdn-images-1.medium.com/max/1024/0*GewXdlScXnhsmcAs.png" /></figure><h4>Syncing MDX</h4><p>Git sync works on top of <em>Input</em>/<em>Output Content Transformers</em> — functions that can “transform” the content to and from the Vrite’s JSON format and whatever’s in your repo. This is quite versatile, and — in theory — should be able to support all kinds of formats, decoupling the format you use from the tooling and features you have available.</p><p>Vrite comes with a <a href="https://github.github.com/gfm/">GitHub-Flavored Markdown</a> (GFM) transformer built-in. It supports basic Markdown formatting, with the addition of GFM extensions, like task lists or tables.</p><p>To extend that, Vrite supports <em>“remote” transformers</em> — essentially processing the content on the backend, communicating via batched POST requests.</p><figure><img alt="Custom transformers section in Vrite&#39;s settings" src="https://cdn-images-1.medium.com/proxy/0*B51X6BvvDcApHnnG" /></figure><p>That’s how the new MDX extension works — it registers a new transformer, that processes your content through endpoints, such as POST <a href="https://extensions.vrite.io/mdx/input.">https://extensions.vrite.io/mdx/input.</a></p><figure><img alt="Vrite extensions panel" src="https://cdn-images-1.medium.com/proxy/0*pTIPO63idb6t9uVJ" /></figure><p>So, to use Git sync with your MDX content:</p><ol><li>From the <em>Extensions</em> side panel → Install the MDX extension;</li><li>From the <em>Source control</em> side panel → Configure GitHub as a provider (selecting your repo and branch, path to sync, and <em>MDX</em> as a transformer; Check out <a href="https://vrite.io/blog/notion-like-experience-for-your-git-hub-content/">this blog post</a> to learn more on this configuration;</li><li>After the <em>Initial sync</em>, check out your content and verify if it was synced correctly.</li></ol><h4>Limitations</h4><p>The MDX transformer can handle much more than the built-in Markdown transformer:</p><ul><li>It supports YAML frontmatter, with properties like title, description or slug being synced with Vrite’s metadata.</li><li>It supports the Element block, converting it to MDX, as expected.</li><li>It uses a special &lt;Import&gt; Element to contain the import statements from the MDX file (for better back-and-forth syncing).</li></ul><p>That said, with both the Element block and MDX extension being new features in a project that’s still in Beta, there are also some limitations you have to consider:</p><ul><li>For the Element block, you can only use values that are JSON-parseable. So, e.g. passing JSX element as a prop won’t work for now.</li><li>Element is a block and there’s no support for custom inline formatting as of yet. Thus, if you use inline JSX components in your MDX (e.g &lt;Icon/&gt;, &lt;InlineBadge&gt;...&lt;/InlineBadge&gt;, etc.) — they’ll be omitted.</li><li>If you’re extending MDX for custom use cases, the Git sync isn’t guaranteed to work. The MDX transformers support only more popular customizations (such as title or metadata for codeblocks);</li></ul><p>The end goal with MDX support is to extend the editor to be fully customizable (both inline and block-wise) and provide more documentation and details for users to create custom transformers, to support all kinds of use cases.</p><h3>Bottom Line</h3><p>I fully intend to make Vrite a viable, go-to solution for all developer content needs — one that’s both open-source and extensible, while still providing an integrated, all-in-one experience.</p><p>The Element block is an important milestone towards this goal. With custom inline content and an entire extension system — for extending the editor with WYSIWYG components built on top of custom elements — coming soon, there’s still a lot more in store.</p><p>If you’re interested in the project, consider <a href="https://github.com/vriteio/vrite">leaving a star on GitHub</a> 🌟.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=26f2fe7372e8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ AI Search and Q&A for Your Dev.to Content with Vrite]]></title>
            <link>https://areknawo.medium.com/ai-search-and-q-a-for-your-dev-to-content-with-vrite-d0fb9ad67a4d?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/d0fb9ad67a4d</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[webdev]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Thu, 24 Aug 2023 16:46:03 GMT</pubDate>
            <atom:updated>2025-02-21T15:42:43.173Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*tC7DFCzULVpqpe_d.png" /></figure><p>No one can deny that <strong>ChatGPT</strong> brought Large Language Models (LLMs) into the public spotlight. While LLMs are not perfect, when you think about it, the ability to ask a wide variety of questions and get an answer in seconds is mind-blowing.</p><p>The only thing left is to somehow connect it with your own data and provide a new context for the LLM to source answers from. This is where <strong>text embeddings</strong>, <strong>vector databases</strong>, and <strong>semantic search</strong> come in. However, depending on your use case, implementing the entire stack necessary to power an “AI search” or a Question-and-Answer (Q&amp;A) type of interface might be quite a challenge… but it doesn’t have to be.</p><p>With the latest update, <strong>Vrite</strong> — an <a href="https://github.com/vriteio/vrite">open-source technical content management platform</a> I’m working on — now has a <strong>built-in search</strong> and a Q&amp;A feature to find answers to all the questions related to your content. Both inside Vrite — via a new <strong>command palette</strong> — and outside — via an API. ✨</p><figure><img alt="AI search and Q&amp;A in Vrite&#39;s command palette" src="https://cdn-images-1.medium.com/max/1024/0*E996gqJWju_KLwFn.gif" /></figure><p>This can be used to easily build a new kind of search experience for your blog or to provide answers to user’s questions in your product docs.</p><p>To give you a fun example of that, we’ll go through a process of importing content from the <strong>Dev.to API</strong> to Vrite to search through it, and then see how you can easily implement a semantic search on your own site using Vrite APIs.</p><h3>Setting-up</h3><p>Let’s start by getting into Vrite. You can use <a href="http://app.vrite.io/">the hosted version</a> (free while Vrite is in Beta) or self-host Vrite from <a href="https://github.com/vriteio/vrite">the source code</a> (with better self-hosting support <a href="https://github.com/vriteio/vrite/issues/21">coming soon</a>)</p><p>To import your Dev.to content collection to Vrite, it’d be best to do so in a dedicated <strong>workspace</strong>. In Vrite, you can use workspaces to separate different projects or teams. To create a new one, from the sidebar go to the <em>Workspace</em> section.</p><figure><img alt="Vrite workspace menu" src="https://cdn-images-1.medium.com/max/1024/0*yFWWohQ4KriPpki9.png" /></figure><p>From here, you can both create and switch between different Workspaces. Create one for your Dev.to blog and switch to it.</p><p>With the dedicated workspace ready, you’ll have to create a new <strong>API token</strong> — both in Vrite and Dev.to — to use in the import script.</p><p>To get one in Vrite, go to the <em>Settings</em> side panel → <em>API</em> section → click <em>New API token</em>. From here you’ll have to configure the details and permissions for the new token. Make sure to select <em>Write</em> permission for both <em>Content pieces</em> and <em>Content groups</em>, as these will be necessary to import the content.</p><figure><img alt="Creating a new API token in Vrite" src="https://cdn-images-1.medium.com/max/1024/0*IOS4zvjrEfii8C_B.png" /></figure><p>Once you create it, store the token in a safe place — you won’t be able to see it again.</p><p>To get an API key from Dev.to, go to the <a href="https://dev.to/settings/extensions"><em>Settings</em> → <em>Extensions</em></a> → <em>DEV Community API Keys</em> section → provide a description and click <em>Generate API Key</em>.</p><figure><img alt="Creating an API key in Dev.to" src="https://cdn-images-1.medium.com/max/1024/0*wDnvaRTSQTHTGRLO.png" /></figure><p>You will be able to see your API Key at any time, though you should still keep it secure.</p><h3>Importing Content From Dev.to</h3><p>With API tokens ready, it’s time to prepare an import script.</p><p>With Node.js (v18 or newer) and NPM installed, initialize a new project, install <a href="https://www.npmjs.com/package/@vrite/sdk">Vrite SDK</a>, and create the primary import.mjs file.</p><pre>npm init -y<br>npm install @vrite/sdk<br>touch import.mjs</pre><p>Inside import.mjs, let’s first create a function to fetch your articles from Dev.to.</p><pre>const VRITE_API_TOKEN = &quot;...&quot;;<br>const DEV_API_KEY = &quot;...&quot;;<br><br>const getDevArticles = async (perPage = 1000) =&gt; {<br>  const response = await fetch(<br>    `https://dev.to/api/articles/me/published?per_page=${perPage}`,<br>    {<br>      headers: {<br>        accept: &quot;application/vnd.forem.api-v1+json&quot;,<br>        &quot;api-key&quot;: DEV_API_KEY,<br>      },<br>    }<br>  );<br>  const data = await response.json();<br>  return data.reverse();<br>};</pre><p>From v18, Node.js provides a fetch() API, similar to web browsers, which makes handling network requests much easier. Use it with the proper URL and headers to make a request to the <a href="https://developers.forem.com/api/v1#tag/articles/operation/getUserPublishedArticles">User&#39;s published articles</a> endpoint.</p><p>The Dev.to API implements pagination, with the max value being 1000, so a single request should be enough to retrieve all the articles for most (if not all) users.</p><p>To actually import the content to Vrite, let’s create a separate function.</p><pre>import { createClient } from &quot;@vrite/sdk&quot;;<br>import { gfmInputTransformer } from &quot;@vrite/sdk/transformers&quot;;<br><br>// ...<br><br>const importToVrite = async (numberOfArticles) =&gt; {<br>  const articles = await getDevArticles(numberOfArticles);<br>  const client = createClient({<br>    token: VRITE_API_TOKEN,<br>  });<br><br>  const { id: contentGroupId } = await client.contentGroups.create({<br>    name: &quot;My Dev.to Articles&quot;,<br>  });<br><br>  for await (const article of articles) {<br>    const {<br>      title,<br>      body_markdown,<br>      published_at,<br>      cover_image,<br>      canonical_url,<br>      url,<br>    } = article;<br>    const { content } = gfmInputTransformer(body_markdown);<br>    try {<br>      await client.contentPieces.create({<br>        contentGroupId,<br>        title,<br>        cover_image,<br>        canonicalLink: canonical_url || url,<br>        content,<br>        coverUrl: cover_image,<br>        date: published_at,<br>        members: [],<br>        tags: [],<br>      });<br>      console.log(`Imported article: &quot;${title}&quot;`);<br>    } catch (error) {<br>      console.error(`Could not import article: &quot;${title}&quot;`, error);<br>    }<br>  }<br>};</pre><p>The .mjs extension in newer versions of Node.js allows out-of-the-box use of ESM import syntax, which we use to import Vrite SDK and gfmInputTransformer.</p><p>Vrite SDK provides a few built-in <strong>input</strong> and <strong>output transformers</strong>. These are functions, with standardized signatures to process the content from and into Vrite. In this case, gfmInputTransformer is essentially a <a href="https://github.github.com/gfm/">GitHub Flavored Markdown</a> parser, using <a href="https://marked.js.org/">Marked.js</a> under the hood.</p><p>In the importToVrite() function, we first retrieve articles from DEV using the mechanism discussed before and initialize the Vrite API client. From there, we create a new <strong>content group</strong> for housing the content and loop over the imported articles using for await to create new <strong>content pieces</strong> from them.</p><p>The created pieces include the transformed content and some additional metadata sourced from Dev.to, to easily identify individual pieces.</p><p>With that, all you have to do is call the importToVrite() function with the number of your latest Dev.to articles to import and watch it go! Here’s the entire script:</p><pre>import { createClient } from &quot;@vrite/sdk&quot;;<br>import { gfmInputTransformer } from &quot;@vrite/sdk/transformers&quot;;<br><br>const VRITE_API_TOKEN = &quot;...&quot;;<br>const DEV_API_KEY = &quot;...&quot;;<br><br>const getDevArticles = async (perPage = 1000) =&gt; {<br>  const response = await fetch(<br>    `https://dev.to/api/articles/me/published?per_page=${perPage}`,<br>    {<br>      headers: {<br>        accept: &quot;application/vnd.forem.api-v1+json&quot;,<br>        &quot;api-key&quot;: DEV_API_KEY,<br>      },<br>    }<br>  );<br>  const data = await response.json();<br><br>  return data.reverse();<br>};<br>const importToVrite = async (numberOfArticles) =&gt; {<br>  const articles = await getDevArticles(numberOfArticles);<br>  const client = createClient({<br>    token: VRITE_API_TOKEN,<br>  });<br><br>  const { id: contentGroupId } = await client.contentGroups.create({<br>    name: &quot;My Dev.to Articles&quot;,<br>  });<br><br>  for await (const article of articles) {<br>    const {<br>      title,<br>      body_markdown,<br>      published_at,<br>      cover_image,<br>      canonical_url,<br>      url,<br>    } = article;<br>    const { content } = gfmInputTransformer(body_markdown);<br>    try {<br>      await client.contentPieces.create({<br>        contentGroupId,<br>        title,<br>        cover_image,<br>        canonicalLink: canonical_url || url,<br>        content,<br>        coverUrl: cover_image,<br>        date: published_at,<br>        members: [],<br>        tags: [],<br>      });<br>      console.log(`Imported article: &quot;${title}&quot;`);<br>    } catch (error) {<br>      console.error(`Could not import article: &quot;${title}&quot;`, error);<br>    }<br>  }<br>};<br><br>importToVrite(20);</pre><h3>Search and Q&amp;A in Vrite Dashboard</h3><p>With the content now in Vrite, let’s go back to the dashboard and see how to use the command palette to search right in Vrite.</p><p>When coupled with Vrite support for collaboration, the built-in search and command palette can serve as a great tool when using Vrite as an internal knowledge base.</p><p>To open the palette use ⌘K (on macOS), Ctrl K (on Windows or Linux), or the search button in the dashboard’s toolbar.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*tRN5HLDOZoiSA8G6.png" /></figure><p>The command palette has 3 modes:</p><ul><li><strong>Search</strong> — the default, provides results as you type;</li><li><strong>Command</strong> — can be enabled by typing &gt; in empty search or by clicking the <em>Command</em> button in the bottom-right corner; Allows quick access to various actions available in the current view; You can move back to the search mode by using Backspace in empty input;</li><li><strong>Ask / Q&amp;A</strong> — can be enabled by clicking the <em>Ask</em> button in the top-right corner; Type in your question and click Enter to request an answer;</li></ul><p>Try searching for any term and see results from your various Dev.to blog posts appear.</p><figure><img alt="Vrite AI search in the command palette" src="https://cdn-images-1.medium.com/max/1024/0*2w5MaJS5pX-tlmHE.png" /></figure><p>Vrite indexes entire sections of your content pieces, identified by the title and a set of headings. This allows the LLM to extract the most semantic meaning from the content, which enables vector search to provide better search results for your queries. So, the better you structure your posts the better the search results will be.</p><p>You can also try the Q&amp;A mode, asking any question that there should be an answer for in your content. Upon submission, the prompt is sent together with the context, for GPT-3.5 to generate an answer, which is streamed back to the command palette.</p><figure><img alt="Vrite Q&amp;A in the command palette" src="https://cdn-images-1.medium.com/max/1024/0*80ntKjVmy8UlMKZt.png" /></figure><p>Personally, I was quite impressed with how well the Q&amp;A turned out. Even answers that would require reading through several pieces were generated accurately in seconds. Still, you should keep in mind that this won’t always be the case.</p><h3>Search and Q&amp;A via Vrite API</h3><p>Now, searching through Vrite’s command palette is nice, but the real fun begins when you get to implement this search and Q&amp;A experience on your own blogs and docs via <strong>Vrite API</strong>.</p><p>First, you’ll have to “proxy” Vrite API searches via your own backend or serverless functions, due to CORS and security considerations (especially if your token has powerful permissions). To do so, you’ll have to access Vrite API from Node.js.</p><h4>Search</h4><p>First, make sure to have an API token with at least <em>Read</em> access to <em>Content pieces</em>. With that, you can use the search() method of the API client to retrieve the results.</p><pre>import { createClient } from &quot;@vrite/sdk&quot;;<br><br>const VRITE_API_TOKEN = &quot;...&quot;;<br><br>const search = async (query) =&gt; {<br>  const client = createClient({<br>    token: VRITE_API_TOKEN,<br>  });<br><br>  const results = await client.search({ query });<br><br>  console.log(results);<br>};<br><br>search(&quot;Dev.to&quot;);</pre><p>The search result is an array of objects, each containing:</p><ul><li>contentPieceId — ID of the related content piece;</li><li>breadcrumb — an array of the title and headings leading to the section;</li><li>content — plain text content of the section;</li></ul><p>You can process or send these results directly to the frontend as a JSON array.</p><h4>Q&amp;A</h4><p>Q&amp;A is a bit more difficult. Due to the slow response associated with the time GPT-3.5 needs to generate an answer, the /search/ask endpoint is implemented via <a href="https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events">Server Sent Events</a> (SSEs) to stream the answer to the user, allowing them to see the first tokens as soon as they’re ready.</p><p>Vrite SDK doesn’t support SSE streaming just yet, so, for now, you’ll have to implement this yourself. Use the <a href="https://www.npmjs.com/package/eventsource">eventsource</a> library or similar to connect with the endpoint and stream the answer.</p><pre>const streamAnswer = async (query) =&gt; {<br>  try {<br>    const source = new EventSource(<br>      `https://api.vrite.io/search/ask?query=${encodeURIComponent(query)}`,<br>      {<br>        headers: { Authorization: `Bearer ${VRITE_API_TOKEN}` },<br>      }<br>    );<br><br>    let content = &quot;&quot;;<br><br>    return new Promise((resolve, reject) =&gt; {<br>      source.addEventListener(&quot;error&quot;, (event) =&gt; {<br>        if (event.message) {<br>          return reject(event.message);<br>        } else {<br>          source.close();<br>          return resolve(content);<br>        }<br>      });<br>      source.addEventListener(&quot;message&quot;, (event) =&gt; {<br>        content += decodeURIComponent(event.data);<br>      });<br>    });<br>  } catch (error) {<br>    console.log(error);<br>  }<br>};<br><br>streamAnswer(&quot;What is Dev.to?&quot;).then((answer) =&gt; {<br>  console.log(answer);<br>});</pre><p>The example loads the entire answer and then resolves the Promise. You can use this method directly, but the response time for each request will be counted in seconds.</p><p>To provide a better User Experience (UX), you’ll likely want to forward the events coming from Vrite API, through your backend to the frontend, where the user will see the first tokens of the answer appear much faster. The implementation of this will depend on your backend framework, but the general approach is to write a text/event-stream response as the data comes in. Here’s a <a href="https://www.digitalocean.com/community/tutorials/nodejs-server-sent-events-build-realtime-app">good overview of the general process</a>.</p><p>I’m working to document and support this process better in the coming weeks.</p><h3>Bottom Line</h3><p>While the AI search itself is really great, the best part about Vrite is that the search is only a small fraction of a greater whole. With the <strong>Kanban</strong> content management, <strong>WYSIWYG</strong> technical content <strong>editor</strong>, <a href="https://vrite.io/blog/notion-like-experience-for-your-git-hub-content/">Git sync</a>, and <strong>extensions for publishing</strong> to platforms like Dev.to with just drag and drop — we’ve only scratched the surface of what’s possible!</p><p>Now, Vrite is currently in Beta and there are still bugs to be resolved, and new features to be added and fleshed out. If you want to help and support the project, <a href="https://github.com/vriteio/vrite">leave a star on GitHub</a> and report any issues or bugs you encounter. With your support, I hope to make Vrite the go-to, open-source technical content platform 🔥</p><ul><li>🔥 <a href="https://app.vrite.io/">Try out Vrite</a></li><li>ℹ️ <a href="https://docs.vrite.io/">Documentation</a></li><li>💬 <a href="https://discord.gg/yYqDWyKnqE">Join Discord</a></li><li>🐦 <a href="https://twitter.com/vriteio">Follow on Twitter</a></li><li>💼 <a href="https://www.linkedin.com/company/vrite">Follow on LinkedIn</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d0fb9ad67a4d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[✍️ Notion-like Experience for Your GitHub Content]]></title>
            <link>https://areknawo.medium.com/%EF%B8%8F-notion-like-experience-for-your-github-content-3f1a4161e626?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/3f1a4161e626</guid>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[open-source]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Tue, 22 Aug 2023 17:54:28 GMT</pubDate>
            <atom:updated>2023-08-22T17:54:28.965Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*4piewOM1Od3zLXAs.png" /></figure><p>A vast amount of technical content — technical blogs, product docs, and others — lives inside <strong>Git repos</strong> — and for a good reason. Aside from Git’s version control, platforms like <a href="https://github.com/">GitHub</a> provide tons of integrations and additional features, to easily host and automate various workflows. That’s especially important for efficient content delivery for blogs, or for docs to be kept in sync and right beside the documented codebase.</p><p>That’s why, while working on <a href="https://github.com/vriteio/vrite">Vrite — an open-source technical content platform</a> — I knew a good integration with Git is crucial for many workflows. It’s a must-have feature, that has to be implemented right for technical writers to benefit from it.</p><p>So, after weeks of research and development, I’m excited to share with you what I’ve come up with, and how you can use Vrite to <strong>edit your GitHub content</strong>.</p><figure><img alt="Vrite WYSIWYG editor" src="https://cdn-images-1.medium.com/max/1024/0*GysAW7NNgbV6CGH0.png" /></figure><h3>The Various Types of Git Integrations</h3><p>Naturally, the idea of integrating Git into a Notion-like, modern, collaborative, WYSIWYG editing environment is nothing new. However, not all Git integrations are created equal.</p><p>Some <strong>Content Management Systems</strong> (CMSs) similar in functionality to Vrite are <strong>Git-based</strong>, meaning they fundamentally rely on Git to work. While that implies great Git integration, it also comes with <a href="https://strapi.io/blog/git-based-vs-api-first-cms">various limitations</a>.</p><p>Vrite leans more towards headless, <strong>API-first</strong> CMS, storing its content in a database, and making it accessible via API for users to build custom frontends on top of. This means that Git becomes a separate layer that has to be integrated into existing tooling.</p><p>CMSs and tools like knowledge bases approach this in various ways. Most commonly I’ve seen a one-way integration, meaning either your Single Source of Truth (SSOT) is a Git repo and every change has to be immediately committed to it or your SSOT is the actual app and you can commit changes in batches, with little to no regard for content or updates that happen in the repo. There seem to also be other solutions, like <a href="https://github.com/vriteio/vrite/discussions/15">periodic sync</a>, where a forceful sync happens every once in a while.</p><p>To me, all these approaches seemed inferior to what developers have at their disposal in code editors and IDEs — including the ability to commit and pull at any time, resolve merge conflicts when necessary, switch between branches, stage certain changes, etc. I wanted to recreate at least a part of that in Vrite by integrating with various Git providers via their APIs — starting with GitHub.</p><h3>Vrite Git Sync</h3><p>So, how does Git sync currently work in Vrite? Let me take you through a quick overview.</p><h4>Setting Up Sync with GitHub</h4><p>You can use Vrite via the <a href="https://app.vrite.io/">hosted version</a> (that’s free while in Beta) or self-host it from the open-source repo (though <a href="https://github.com/vriteio/vrite/issues/21">good support for self-hosting</a> is still in the works).</p><figure><img alt="Signing in to Vrite" src="https://cdn-images-1.medium.com/max/1024/0*9G5OvX12YFomZu-y.png" /></figure><p>When inside the dashboard, open the <em>Source control</em> side panel.</p><figure><img alt="Source control side panel" src="https://cdn-images-1.medium.com/max/1024/0*TdQ6G78aL0u9MME4.png" /></figure><p>From here, you’ll have to first select and configure a provider. For now, only GitHub is supported, with other major providers (GitLab, BitBucket, and Gitea) to come later.</p><figure><img alt="Configuring GitHub provider" src="https://cdn-images-1.medium.com/max/1024/0*aW1oTrsDU5sOEr-0.png" /></figure><p>To configure GitHub you’ll first have to select a repo and authorize access to it. To do so, first, authenticate with GitHub, and <a href="https://github.com/apps/vrite-io/installations/select_target">install the Vrite GitHub app</a>. Only accounts and repos authorized in the GitHub App’s installation will be available for selection.</p><figure><img alt="Configuring mapping settings" src="https://cdn-images-1.medium.com/max/1024/0*-MdGV_yruf2TrS5Q.png" /></figure><p>After you’ve selected the repo and branch to sync, you can optionally configure the mapping settings. These dictate how to map the repository’s content to Vrite.</p><ul><li><strong>Base directory</strong> — indicates which directory to sync with, so you can only sync e.g. /docs directory. It points to the root (/) directory by default.</li><li><strong>Match pattern</strong> — a glob match pattern that, applied relative to the base directory, will only sync files with matched filenames. By default, it matches all .md files.</li></ul><figure><img alt="Initial sync section" src="https://cdn-images-1.medium.com/max/1024/0*97wF4XQePF6PD2Ua.png" /></figure><p>Once you configure GitHub provider, and <em>Save</em> the configuration, you’ll have to perform the <strong>initial sync</strong>. That’s when the existing content from GitHub will be synced into Vrite, creating content groups for all the folders, content pieces for synced files, and indexing it all. Depending on the amount of content you have, this can take a while.</p><h4>Managing Content In Vrite</h4><p>Once the sync is complete, you’ll see a new content group appear, with a name corresponding to your repo.</p><figure><img alt="After initial sync" src="https://cdn-images-1.medium.com/max/1024/0*tsuPI14v41ow7EfO.png" /></figure><p>Now, a word on managing your Git content in Vrite.</p><p>In Vrite, your content is organized into <strong>content pieces</strong> — containing the actual content and related metadata, and <strong>content groups</strong> — grouping multiple content pieces together. In the Vrite dashboard’s primary view — Kanban — these are displayed as individual draggable columns and cards inside them.</p><p>Kanban is great for managing the content production process, but it doesn’t necessarily represent the way your Git repo is structured — with nested folders and all. That’s why, to provide a good experience for the new workflow with Git, Vrite now supports <strong>nested content groups</strong>.</p><p>To navigate those, you can use the <strong>folder icon</strong>, next to the content group’s name. Click it to get inside the content group, and drag it onto the other folder icon to move one group into the other.</p><figure><img alt="Folder icon and breadcrumb in use" src="https://cdn-images-1.medium.com/max/1024/0*gGk8D5vNRud9-CfZ.png" /></figure><p>The same dragging and clicking mechanism works with the <strong>breadcrumb</strong> that will appear in the toolbar. Simply click a content group (or the workspace icon) to get back to the certain nesting level, or drag a folder icon from the Kanban onto one part of the breadcrumb to move it.</p><p>Why use the folder icon for that? I think it’s a more intuitive way to manage group nesting while dragging entire columns is still reserved for rearranging the kanban.</p><p>But that’s not all. If you prefer a more folder-like approach to managing your content, you can always switch to the new <strong>list view</strong>, similar to the one you’ve experienced in GitHub. The same rules apply here, with the additional option to also drag individual content pieces onto the groups’ folder icons to move them. This feature is to-be-added in the Kanban view.</p><figure><img alt="List view" src="https://cdn-images-1.medium.com/max/1024/0*8YIjnu0NP4JcBzf5.png" /></figure><p>One more thing to note is in regard to filename mapping. Vrite supports various metadata for content pieces, including <strong>title</strong> and <strong>slug</strong>, but these didn’t seem appropriate to use for filename mapping. What if you want to use the title for something meaningful, or the slug for publishing on your blog, docs, etc.? That’s why Vrite added a new metadata field called <strong>Filename</strong>, which is specifically meant to aid in use cases like Git integration, assigning a meta filename to your piece.</p><figure><img alt="Content piece metadata" src="https://cdn-images-1.medium.com/max/1024/0*ygajWVZ2HlgrBn15.png" /></figure><p>However, with the increased number of metadata fields, I’ve decided to keep some (including filename) disabled by default, to allow you to better focus on the metadata that matters to you. So, if you use Git, you’ll likely want to go to the <em>Settings</em> → <em>Metadata</em> section and enable the fields that matter to you.</p><figure><img alt="Metadata settings" src="https://cdn-images-1.medium.com/max/1024/0*bkiaxPL7rHDXAs29.png" /></figure><h4>Pull, Commit &amp; Resolve Changes</h4><p>Knowing how to manage content in Vrite, let’s go back to the Source control panel and see how to sync your edits with Git.</p><p>First — <strong>commits</strong>. Go to the editor and edit a piece or two. You should see the changed files reflected in the <em>Changes</em> section shortly after. In case you want to commit the changes, simply provide a <em>Commit message</em> and commit.</p><figure><img alt="Commiting changes" src="https://cdn-images-1.medium.com/max/1024/0*epVHk5xe1BmMCkTk.png" /></figure><p>The commit should show up in the repo as verified and authored by <strong>vrite-io[bot]</strong>. I decided against attributing changes to individual users, as Vrite enables you to add team members and collaborate on the content in real time, making it difficult to differentiate who actually made the change.</p><p>Now, when you try to commit after a change has been done to the repo from outside your Vrite account, you’ll receive a <em>“Pull required before committing changes”</em> error notification. To resolve this, you’ll have to first <strong>pull the latest changes</strong>.</p><p>To do so, simply use the button in the <em>Pull</em> section. Vrite will fetch all commits made since the last pull (or the initial sync) and sync the content of files changed in those commits. It can be done entirely automatically, or there can be a <strong>conflict</strong>. In this case, you’ll have to resolve it first, before you can sync the changes.</p><figure><img alt="Pull and resolve conflicts" src="https://cdn-images-1.medium.com/max/1024/0*6CempALI_LLOc8MY.png" /></figure><p>All conflicted files will be listed in the Pull section. Click on one of them to start resolving the conflict.</p><figure><img alt="Resolving conflicts" src="https://cdn-images-1.medium.com/max/1024/0*codyW3PmmXchaXxQ.png" /></figure><p>You’ll see a <a href="https://microsoft.github.io/monaco-editor/">Monaco Editor</a>-powered change editor. The content incoming from the Git repo is on the left, while the current content in Vrite is on the right. You can make changes in the editor on the right — this will ultimately become the result content. Once you’re done, click <em>Resolve</em>. If there are no other conflicts, you should now be able to pull the latest changes.</p><h3>Future Improvements</h3><p>With that, you now know pretty much all there is to know about GitHub sync in Vrite. It’s quite simple and still not as feature-rich as you can find in code editors or IDEs, but it gets the job done, better than quite a few other CMS and knowledge-base tools.</p><p>That said, there’s definitely room to improve. I’d like Vrite to be the “go-to” editor/CMS for blogs and docs, and this necessitates some additional features. In the short term, I’m looking to add:</p><ul><li><strong>Custom remote transformers</strong> — to allow developers to provide custom functions for processing content in and out of Vrite;</li><li><strong>Stage</strong> and <strong>undo</strong> — to better organize the commits from Vrite;</li><li><strong>Custom blocks</strong> — to extend the content that can be synced with and edited in Vrite, to support more use cases, like complex, custom docs;</li></ul><p>In the long-term:</p><ul><li>Support for other providers;</li><li>Easy switching between branches;</li><li>Custom WYSIWYG editor for conflict resolution;</li><li>Access to your Git version history right from Vrite;</li></ul><h3>Bottom Line</h3><p>Syncing the content from GitHub with Vrite allows you to have a great WYSIWYG editing experience for your technical content, while still having access to all the features of Git and GitHub. In addition to that, you get to benefit from all the features of Vrite, like easy content management, powerful API with Webhooks, and… an <strong>AI search</strong>, though that’s a story for another day.</p><p>In case you’re interested in Vrite, <a href="https://github.com/vriteio/vrite">leave a 🌟 on GitHub</a>, as well as any feature requests or issues you may have, to support the project. ❤️</p><ul><li>🔥 <a href="https://app.vrite.io/">Try out Vrite</a></li><li>ℹ️ <a href="https://docs.vrite.io/">Documentation</a></li><li>💬 <a href="https://discord.gg/yYqDWyKnqE">Join Discord</a></li><li>🐦 <a href="https://twitter.com/vriteio">Follow on Twitter</a></li><li>💼 <a href="https://www.linkedin.com/company/vrite">Follow on LinkedIn</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3f1a4161e626" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building an Extension System on the Web]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://areknawo.medium.com/building-an-extension-system-on-the-web-dfd73d4c0d71?source=rss-703e187f4ea2------2"><img src="https://cdn-images-1.medium.com/max/2400/0*5eRiEMCD4pPJQnbW.png" width="2400"></a></p><p class="medium-feed-snippet">Building an extension system is no small feat&#x200A;&#x2014;&#x200A;especially on the Web. Here&#x2019;s how it was implemented in Vrite&#x2026;</p><p class="medium-feed-link"><a href="https://areknawo.medium.com/building-an-extension-system-on-the-web-dfd73d4c0d71?source=rss-703e187f4ea2------2">Continue reading on Medium »</a></p></div>]]></description>
            <link>https://areknawo.medium.com/building-an-extension-system-on-the-web-dfd73d4c0d71?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/dfd73d4c0d71</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[webdev]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Sun, 06 Aug 2023 10:50:03 GMT</pubDate>
            <atom:updated>2023-08-06T10:50:03.051Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[Vrite Editor: Open-Source WYSIWYG Markdown Editor]]></title>
            <link>https://areknawo.medium.com/vrite-editor-open-source-wysiwyg-markdown-editor-cfe2b44776b9?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/cfe2b44776b9</guid>
            <category><![CDATA[webdev]]></category>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[open-source]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Tue, 18 Jul 2023 17:58:15 GMT</pubDate>
            <atom:updated>2023-07-18T17:58:15.038Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*dvMGAkL3Jf8BqT2q.png" /></figure><p>I’ve created an <a href="https://github.com/vriteio/vrite">open-source</a>, <a href="https://editor.vrite.io/">minimalistic WYSIWYG Markdown editor</a> to easily create and export Markdown and HTML content on the go, without any sign-up required!</p><p>Here’s “Why?”, “How?”, and other questions answered!</p><h3>The “Why?”</h3><p>In software development, Markdown is basically omnipresent. You can find it in READMEs, powering software blogs, and serving as one of the primary content formatting methods when <strong>Rich Text Editing</strong> (RTE) is required.</p><p>Markdown is awesome! But, when writing 1000 words+ articles, I quickly feel the need for a better experience. For years, I’ve used <a href="https://stackedit.io/">StackEdit</a> — an open-source, in-browser Markdown editor — for editing all kinds of long-format Markdown text. That said, given my recent experience with WYSIWYG editors, I thought I could do something better.</p><p>That’s how I created <strong>Vrite Editor</strong> — an open-source Rich Text Editor, focused on good user experience and technical writing.</p><figure><img alt="Vrite Editor" src="https://cdn-images-1.medium.com/max/1024/0*0JEFWsDBtUew6FL-.png" /></figure><h3>The Stack</h3><p>No good tool is built without using good tools, and Vrite Editor is no different. Before getting into WYSIWYG editors, I <a href="https://vrite.io/blog/best-js-rich-text-editors-for-2023/">extensively researched available RTE frameworks</a>, that could provide the tooling and functionality I was looking for. Ultimately, I picked <a href="https://tiptap.dev/">TipTap</a> and underlying <a href="https://prosemirror.net/">ProseMirror</a> — IMO, the best tools currently available for all kinds of WYSIWYG editors.</p><p>Aside from that, I used:</p><ul><li><a href="https://solidjs.com/">Solid.js</a> — the super-fast UI framework;</li><li><a href="https://unocss.dev/">UnoCSS</a> — for styling with Tailwind-like atomic CSS;</li><li><a href="https://vitejs.dev/">Vite</a> — build tool for putting it all together;</li></ul><p>The results came out pretty nicely! 🌟</p><h3>Features &amp; Behind the Scenes</h3><p>Vrite Editor comes with many features to make editing a breeze! You can check them all out in <a href="https://docs.vrite.io/content-editor/">the official documentation</a>. That said, there are a few unique ones that I feel are worth diving deeper into.</p><h4>Code Editor</h4><p>Something that I always felt was lacking in WYSIWYG editors (even the top ones, like <a href="https://notion.so/">Notion</a>) is good support for <strong>code editing</strong>. Granted, technical writing is a niche use-case and you can get by with simple syntax highlighting and some copy-pasting. That said, I wanted to try something else — I wanted to integrate a full-blown code editor.</p><figure><img alt="Integrated code editor" src="https://cdn-images-1.medium.com/max/1024/0*XTcxwGrrdld0KNmj.png" /></figure><p>By referencing <a href="https://prosemirror.net/examples/codemirror/">the ProseMirror docs</a>, forwarding the editor state back and forth, and adjusting the layout, I managed to integrate <a href="https://microsoft.github.io/monaco-editor/">Monaco Editor</a> — the web editor extracted from VS Code — together with <a href="https://prettier.io/">Prettier</a> (for code formatting) right into the Vrite Editor (I know, that’s a lot of editors in one place 😅).</p><p>Granted, this is not VS Code in your content editor, but this way you get great syntax highlighting for many languages, while also having formatting and auto-completion for at least a few — like JavaScript or HTML.</p><h4>Table Editor</h4><p>The “whole grail of WYSIWYG editing” (as stated in <a href="https://tiptap.dev/api/nodes/table#introduction">the TipTap docs</a>) took a while to get right. While TipTap provides extensions for supporting Table formatting, the UI is a different story. Table formatting UIs are notoriously difficult to get right. That’s why I was quite happy when I finally felt like I built something that was… alright.</p><figure><img alt="Table editor" src="https://cdn-images-1.medium.com/max/1024/0*mbN4wWquCOIRCN5g.png" /></figure><p>When your cursor is inside the table, you’ll see a bottom menu appear, which you can use e.g. insert and remove rows, columns, and headers. On the other hand, when you select some cells, you’ll see a menu to e.g. merge, split, or delete them. It’s not Excel-level but, for an inline table, I think it’s pretty good.</p><h4>Markdown Pasting</h4><p>Handling Markdown pasting was a surprising challenge. Naturally, you’d expect an editor that works with Markdown to be able to parse and properly load the Markdown you pasted, so some work had to go into that.</p><p>TipTap provides <a href="https://tiptap.dev/guide/custom-extensions/#input-rules">input rules</a> to handle so-called “Markdown shortcuts” while typing, and <a href="https://tiptap.dev/guide/custom-extensions/#paste-rules">paste rules</a> for offering the same parsing functionality while pasting. The problem is, paste rules work line-by-line, which means parsing something like a blockquote, codeblock, or a list, just isn’t possible.</p><p>To handle pasting block Markdown content like this, I had to tap into ProseMirror and implement a custom mechanism (though somewhat based on TipTap’s paste rules), detecting starting and ending points of the blocks and parsing them with <a href="https://marked.js.org/">Marked.js</a>.</p><p>Thankfully, with this done, most Markdown can be pasted freely into the editor and should be parsed just fine!</p><h4>Mobile Support</h4><p>The other thing that’s quite hard to get right in a web-based WYSIWYG editor, is <strong>mobile support</strong>.</p><p>Initially, I thought that a good editing experience on the mobile platform can only be achieved with a native mobile app, so why bother trying to get it right on the mobile web?</p><p>Well, ultimately I tried to add mobile support to Vrite Editor anyway, and, to my surprise, it turned out pretty good!</p><figure><img alt="Vrite on Mobile" src="https://cdn-images-1.medium.com/max/1024/0*TdGnmBtioNvxeDuT.png" /></figure><p>There were many things that needed optimization — and some that still do. From the general layout, toolbar, and the UI of block elements to formatting and block content menus — everything had to be in some way optimized or completely changed for mobile.</p><p>Now, there’s still some work to be done here. Monaco editor <a href="https://github.com/microsoft/monaco-editor/issues/246">doesn’t work well for mobile</a>, and some “optional” features weren’t yet optimized (like link previews or comments).</p><p>Still, with the work already done, Vrite Editor is usable and actually quite comfortable on mobile.</p><blockquote>By the way, I did write this section on my phone. 😊</blockquote><h4>Markdown Exports</h4><p>Now, with the editor working, the last important part was to output Markdown. TipTap provides methods to retrieve both HTML and ProseMirror JSON representations of the content. I decided to use the JSON (since it’s easier to work with) and created functions to transform it into various outputs. I called these <em>“Content Transformers”</em>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Qv8VRr5mXV2bYPJS.png" /></figure><p>Using Content Transformers I created an “Export” menu, outputting the content in HTML, GitHub Flavored Markdown (GFM), and ProseMirror JSON (e.g. for custom processing) to a Monaco Editor, with options to download or copy it.</p><p>While there might be better ways to do this, this one provides a lot of flexibility and makes sure your content can be properly processed to Markdown or any other format you need.</p><h3>Vrite CMS</h3><p>In case you enjoy using Vrite Editor, you might be interested in a larger project that it’s a part of — “Vrite CMS”, or simply “Vrite”.</p><p><a href="https://vrite.io/">Vrite is a headless CMS for technical content</a>, providing editing and management tools to work with content like technical product documentation, programming blogs, etc. Basically, it’s my answer to (what I consider) a lack of good tooling focused on this kind of content.</p><figure><img alt="Vrite dashboard" src="https://cdn-images-1.medium.com/max/1024/0*GVmXPIvckdV8nup8.png" /></figure><p>Beyond just the Vrite Editor, you get additional features, like:</p><ul><li>Kanban dashboard for content management;</li><li>API and Webhooks;</li><li>Extension system for easy publishing to popular platforms;</li><li>Real-time collaboration;</li><li>and more!</li></ul><p>Since Vrite (and Vrite Editor for that matter) is currently in <strong>Public Beta</strong>, new features and improvements are in active development. The best way to try it out right now is through the hosted version at <a href="https://app.vrite.io/">app.vrite.io</a> (free while in Beta) with better self-hosting support in the works.</p><h3>Bottom Line</h3><p>In any case, if you’re interested in technical writing, definitely check out <a href="https://editor.vrite.io/">Vrite Editor</a> and <a href="https://vrite.io/">Vrite</a> as a whole. Also, <a href="https://github.com/vriteio/vrite">leave a 🌟 on GitHub</a>, as well as any feature requests or issues you may have, to support the project. ❤️</p><ul><li>🔥 <a href="https://app.vrite.io/">Try out Vrite</a></li><li>ℹ️ <a href="https://docs.vrite.io/">Usage guide</a></li><li>🚀 <a href="https://vrite.io/blog">Blog</a></li><li>📝 <a href="https://github.com/vriteio/vrite/issues">Report a bug</a></li><li>🙋‍♀️ <a href="https://github.com/vriteio/vrite/discussions">Request a feature</a></li><li>💬 <a href="https://discord.gg/yYqDWyKnqE">Join Discord</a></li><li>🐦 <a href="https://twitter.com/vriteio">Follow on Twitter</a></li><li>💼 <a href="https://www.linkedin.com/company/vrite">Follow on LinkedIn</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cfe2b44776b9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How I put ChatGPT into a WYSIWYG editor]]></title>
            <link>https://areknawo.medium.com/how-i-put-chatgpt-into-a-wysiwyg-editor-39e97f86e34?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/39e97f86e34</guid>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[webdev]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Mon, 19 Jun 2023 20:47:19 GMT</pubDate>
            <atom:updated>2023-06-19T20:47:19.815Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*RTob4h_mQcdVoipJ.png" /></figure><p>With all the hype going on, AI (or rather <em>Machine Learning</em> (ML) and <em>Large Language Models</em> (LLMs) are everywhere. Personally, I might not use ChatGPT (and similar alternatives) much, but I sure do rely on likes of <a href="https://github.com/features/copilot">GitHub Copilot</a> (for intelligent autocompletion in VS Code), or <a href="https://www.grammarly.com/">Grammarly</a> (for editing my blog posts) every day.</p><p>I think we’re still quite a few breakthroughs away from AGI and current technology won’t be enough to get us there (thankfully or not). That said, we’re already deep into the times of <em>“AI-enhanced”</em> apps, where the apps at the top may not have the best AI systems, but they integrate them in the best possible way.</p><p>That’s why it was an interesting process, exploring OpenAI’s API and trying to integrate it into the Rich Text Editor (RTE) of Vrite — my open-source headless CMS.</p><h3>Extending the WYSIWYG Editor</h3><p>For those unfamiliar Vrite, in a nutshell, is a headless CMS for technical content, like programming blogs or software docs. It can be viewed as two apps in one — Kanban dashboard for content management and WYSIWYG editor for writing, with additional dev-friendly features like embedded code snippet editor and formatter.</p><p>The latest big addition to Vrite is an early extension system, to easily build integrations and extend what Vrite can do. This, to me, seemed like the perfect way to introduce ChatGPT into the editor — as an <strong>extension</strong>.</p><h4>Block Actions</h4><p>To be able to use the extension system for integrating ChatGPT into the editor, a new API had to be introduced. I called it <em>Block Action API</em> since its specifically meant for adding quick actions to the editor, that operate on top-level content blocks, like paragraphs, headings, or images, as is highlighted below:</p><figure><img alt="Content blocks in Vrite editor - highlighted" src="https://cdn-images-1.medium.com/max/1024/0*G6oTkjaCqMXH4cfn.png" /></figure><p>With Block Actions API, extensions can read the JSON content of the active block and update it with HTML-formatted content, just like it’s done in Vrite API (on one end, parsing JSON output is easier while, on the other, HTML is more suitable to transform content into).</p><p>From the UI side, Block Actions are displayed as buttons on the side of the actively-selected block. They can either invoke an action directly on click or — like with ChatGPT — open a dropdown menu to prompt the user for more details.</p><figure><img alt="GPT-3.5 extension&#39;s Block Action dropdown" src="https://cdn-images-1.medium.com/max/1024/0*SKu3G1OI8w1gZZwG.png" /></figure><p>The buttons had to be absolutely positioned, which required both a custom <a href="https://tiptap.dev/">TipTap</a> extension and tapping deeper into the underlying <a href="https://prosemirror.net/">ProseMirror</a> (both libraries powering the Vrite editor).</p><p>The process basically came down to figuring out the position and size of the block node, given a selection of an entire top-level node or just its child node (<a href="https://github.com/vriteio/vrite/blob/5acb789dc2a92a6da75daf062065ee5c164b4608/apps/web/src/lib/editor/extensions/block-action-menu/plugin.tsx">source code</a>):</p><pre>// ...<br>const BlockActionMenuPlugin = Extension.create({<br>  // ...<br>  onSelectionUpdate() {<br>    const { selection } = this.editor.state;<br>    const isTextSelection = selection instanceof TextSelection;<br>    const selectedNode = selection.$from.node(1) || selection.$from.nodeAfter;<br><br>    if (!selectedNode) {<br>      box.style.display = &#39;none&#39;;<br>      return;<br>    }<br><br>    const { view } = this.editor;<br>    const node =<br>      view.nodeDOM(selection.$from.pos) ||<br>      view.nodeDOM(selection.$from.pos - selection.$from.parentOffset) ||<br>      view.domAtPos(selection.$from.pos)?.node;<br><br>    if (!node) return;<br><br>    const blockParent = getBlockParent(node);<br>    const parentPos = document<br>      .getElementById(&#39;pm-container&#39;)<br>      ?.getBoundingClientRect();<br>    const childPos = blockParent?.getBoundingClientRect();<br><br>    if (!parentPos || !childPos) return;<br><br>    const relativePos = {<br>      top: childPos.top - parentPos.top,<br>      right: childPos.right - parentPos.right,<br>      bottom: childPos.bottom - parentPos.bottom,<br>      left: childPos.left - parentPos.left,<br>    };<br><br>    let rangeFrom = selection.$from.pos;<br>    let rangeTo = selection.$to.pos;<br><br>    box.style.top = `${relativePos.top}px`;<br>    box.style.left = `${relativePos.left + parentPos.width}px`;<br>    box.style.display = &#39;block&#39;;<br><br>    if (isTextSelection) {<br>      try {<br>        const p = findParentAtDepth(selection.$from, 1);<br>        rangeFrom = p.start - 1;<br>        rangeTo = p.start + p.node.nodeSize - 1;<br>      } catch (e) {<br>        box.style.display = &#39;none&#39;;<br>      }<br>    }<br><br>    // ...<br>  },<br>});</pre><h4>Replacing Editor Content</h4><p>The second part involved handling the actual process of replacing the block’s content with the newly provided one. The trickiest thing to figure out here was to get the correct range (the start and end position in ProseMirror) of the block node. This was necessary to then use TipTap’s commands to properly replace the range.</p><p>If you’ve taken a closer look at the last code snippets — the code for that was already there. The block’s range was updated, together with the Block Action UI positioning, on every selection update.</p><p>The actual replacement of the range with new content was much easier to do. All there was to it was converting the HTML to Schema-adherent JSON and involving proper commands (<a href="https://github.com/vriteio/vrite/blob/5acb789dc2a92a6da75daf062065ee5c164b4608/apps/web/src/lib/editor/extensions/block-action-menu/component.tsx">source code</a>):</p><pre>// ...<br>const replaceContent = (content) =&gt; {<br>  unlock.clear();<br>  setLocked(true);<br>  if (range()) {<br>    let size = 0;<br>    const nodeOrFragment = createNodeFromContent(<br>      content,<br>      props.state.editor.schema<br>    );<br><br>    if (nodeOrFragment instanceof PMNode) {<br>      size = nodeOrFragment.nodeSize;<br>    } else {<br>      size = nodeOrFragment.size;<br>    }<br>    props.state.editor<br>      .chain()<br>      .focus()<br>      .insertContentAt(<br>        range()!,<br>        generateJSON(content, props.state.editor.extensionManager.extensions)<br>      )<br>      .scrollIntoView()<br>      .focus()<br>      .run();<br>    setRange({ from: range()!.from, to: range()!.from + size - 1 });<br>    computeDropdownPosition()();<br>  }<br>  unlock();<br>};<br>// ...</pre><p>The replaceContent() function could then be called remotely, from the extension’s sandbox, by sending a proper message to the main frame.</p><p>To enable use-cases like ChatGPT integrations, where the content will be updated (i.e. replaced) multiple times in a row before the process is finished, the function also locked the editor for a short time of the function being called and updated the range, and UI positioning on every call. But why was this required?</p><h3>Integrating With OpenAI’s API</h3><p>The process of integrating OpenAI’s API is pretty well-documented in <a href="https://platform.openai.com/docs/api-reference/chat/create">its official docs</a>. Given that an official SDK is provided, the entire process can be done in just a few lines of code:</p><pre>async ({ ctx, input }) =&gt; {<br>  const configuration = new Configuration({<br>    apiKey: ctx.fastify.config.OPENAI_API_KEY,<br>    organization: ctx.fastify.config.OPENAI_ORGANIZATION,<br>  });<br>  const openai = new OpenAIApi(configuration);<br>  const response = await openai.createChatCompletion({<br>    model: &#39;gpt-3.5-turbo&#39;,<br>    messages: [{ role: &#39;user&#39;, content: input.prompt }],<br>  });<br>};</pre><p>Now, all that is true, but only if you’re willing to wait what often is <strong>+20s</strong> for a single response! That’s a lot for a single request. Nothing from changing the server location to optimizing the request by limiting max_tokens or customizing other parameters worked. It all comes down to the fact that current-day LLMs (those on the level of GPT-3 at least) are still rather slow.</p><p>With that said, the ChatGPT app still manages to be perceived as fairly fast and responsive. That’s thanks to the use of streaming and <strong>Server-Sent Events</strong> (SSEs).</p><h4>Streaming ChatGPT Response</h4><p>The chat completion and other endpoints of OpenAI’s API support streaming through Server-Sent Events, essentially maintaining an open connection through which the new tokens are sent as soon as they’re available.</p><p>Unfortunately, the official Node.js SDK <a href="https://github.com/openai/openai-node/issues/18">doesn’t support streaming</a> and requires you to use workarounds to get it working, resulting in much more code required, just to connect with the API (<a href="https://github.com/vriteio/vrite/blob/5acb789dc2a92a6da75daf062065ee5c164b4608/apps/backend/extensions/src/routes/gpt.ts">source code</a>):</p><pre>async ({ ctx, input }) =&gt; {<br>  const configuration = new Configuration({<br>    apiKey: ctx.fastify.config.OPENAI_API_KEY,<br>    organization: ctx.fastify.config.OPENAI_ORGANIZATION,<br>  });<br>  const openai = new OpenAIApi(configuration);<br>  const response = await openai.createChatCompletion(<br>    {<br>      model: &#39;gpt-3.5-turbo&#39;,<br>      stream: true,<br>      messages: [{ role: &#39;user&#39;, content: input.prompt }],<br>    },<br>    { responseType: &#39;stream&#39; }<br>  );<br>  ctx.res.raw.writeHead(200, {<br>    ...ctx.res.getHeaders(),<br>    &#39;content-type&#39;: &#39;text/event-stream&#39;,<br>    &#39;cache-control&#39;: &#39;no-cache&#39;,<br>    connection: &#39;keep-alive&#39;,<br>  });<br><br>  return new Promise&lt;void&gt;((resolve) =&gt; {<br>    const responseData = response.data as unknown as {<br>      on(event: string, data: (data: string) =&gt; void): void;<br>    };<br><br>    responseData.on(&#39;data&#39;, (data) =&gt; {<br>      const lines = data<br>        .toString()<br>        .split(&#39;\n&#39;)<br>        .filter((line) =&gt; line.trim() !== &#39;&#39;);<br>      for (const line of lines) {<br>        const message = line.replace(/^data: /, &#39;&#39;);<br>        if (message === &#39;[DONE]&#39;) {<br>          ctx.res.raw.end();<br>          resolve();<br>          continue;<br>        }<br>        try {<br>          const parsed = JSON.parse(message);<br><br>          const content = parsed.choices[0].delta.content || &#39;&#39;;<br><br>          if (content) {<br>            ctx.res.raw.write(`data: ${encodeURIComponent(content)}`);<br>            ctx.res.raw.write(&#39;\n\n&#39;);<br>          }<br>        } catch (error) {<br>          console.error(&#39;Could not JSON parse stream message&#39;, message, error);<br>        }<br>      }<br>    });<br>  });<br>};</pre><p>On top of that, you also have to support streaming on your end, between your API server and web client which, in the case of Vrite, meant integrating SSEs with <a href="https://www.fastify.io/">Fastify</a> and <a href="https://trpc.io/">tRPC</a>. Not the cleanest solution, but pretty stable nonetheless.</p><p>From the frontend (the extension sandbox to be precise), a connection with the new streaming endpoint has to be established and incoming data — correctly processed (<a href="https://github.com/vriteio/vrite/blob/5acb789dc2a92a6da75daf062065ee5c164b4608/packages/extensions/src/gpt-3.5/functions/generate.ts">source code</a>):</p><pre>import { fetchEventSource } from &quot;@microsoft/fetch-event-source&quot;;<br>// ...<br><br>const generate = async (context: ExtensionBlockActionViewContext): Promise&lt;void&gt; =&gt; {<br>  const includeContext = context.temp.includeContext as boolean;<br>  const prompt = context.temp.prompt as string;<br><br>  let content = &quot;&quot;;<br><br>  context.setTemp(&quot;$loading&quot;, true);<br>  window.currentRequestController = new AbortController();<br>  window.currentRequestController.signal.addEventListener(&quot;abort&quot;, () =&gt; {<br>    context.setTemp(&quot;$loading&quot;, false);<br>    context.refreshContent();<br>  });<br>  await fetchEventSource(&quot;https://extensions.vrite.io/gpt&quot;, {<br>    method: &quot;POST&quot;,<br>    headers: {<br>      &quot;Content-Type&quot;: &quot;application/json&quot;,<br>      &quot;Accept&quot;: &quot;text/event-stream&quot;<br>    },<br>    body: JSON.stringify({<br>      prompt: includeContext ? `&quot;${gfmTransformer(context.content)}&quot;\n\n${prompt}` : prompt<br>    }),<br>    signal: window.currentRequestController?.signal,<br>    async onopen() {<br>      return;<br>    },<br>    onerror(error) {<br>      context.setTemp(&quot;$loading&quot;, false);<br>      context.refreshContent();<br>      context.notify({ text: &quot;Error while generating content&quot;, type: &quot;error&quot; });<br>      throw error;<br>    },<br>    onmessage(event) {<br>      const partOfContent = decodeURIComponent(event.data);<br><br>      content += partOfContent;<br>      context.replaceContent(marked.parse(content));<br>    },<br>    onclose() {<br>      context.setTemp(&quot;$loading&quot;, false);<br>      context.refreshContent();<br>    }<br>  });<br>};</pre><p>The <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventSource">EventSource Web API</a> for handling SSEs (built into most modern browsers) unfortunately supports only GET requests, which was quite limiting when a POST request with larger body JSON data was required. As an alternative, you can use the Fetch API or a ready library like <a href="https://github.com/Azure/fetch-event-source">Microsoft’s Fetch Event Source</a>.</p><p>Again, with streaming enabled, you’ll now receive new tokens as soon as they’re available. Given that OpenAI’s API uses Markdown in its response format, a full message will need to be put together from the incoming tokens and parsed to HTML, as accepted by the replaceContent function. For this purpose, I’ve used the <a href="https://marked.js.org/">Marked.js parser</a>.</p><p>Now, with each new token, the larger response is being built up. Every time a new token comes, the full Markdown is parsed and the content updated, making for a nice “typing-like effect”.</p><p>While this process does have some overhead, it’s not noticeable in use, while the Markdown simply has to be parsed with each new token, as it may contain e.g. the closing of the code block, or the end of the formatted segment. So, while this process could potentially be optimized, it wouldn’t lead to any recognizable performance improvement in the majority of cases.</p><p>Finally, worth noting is the use of AbortController, which can be used to stop the stream at any time the user chooses to. That’s especially great for longer responses.</p><figure><img alt="GPT-3.5 Block Action... in action" src="https://cdn-images-1.medium.com/max/1000/0*ldnJ7DurqQbVR-xp.gif" /></figure><h3>Bottom Line</h3><p>In general, I’m very happy with how this turned out. Data streaming, nice typing effect, and good integration with the editor’s existing content blocks thanks to Markdown parsing — all came together to create a compelling User Experience.</p><p>Now, there’s certainly room for improvement. The Block Actions API, as well as the Vrite Extensions as a whole still have a lot of development work ahead of them before they can be created by other users. Other UI/UX improvements to consider, like operating on multiple blocks at once (e.g. for additional context for ChatGPT) and displaying UI inline (much like Notion AI) not to obscure the view are just a few examples of what I was considering. That said, it’ll take some more time to implement these ideas well.</p><figure><img alt="Vrite Kanban dashboard" src="https://cdn-images-1.medium.com/max/1024/0*5rOjgCopkfuR_k9Q.png" /></figure><p>Vrite is much more than just a GPT-enhanced editor. It’s a full, open-source CMS focused on technical content like programming blogs, with a code editor, API, Kanban management dashboard included and easy publishing integrations included. So, if you’re interested in trying it out and possibly using it to power your blog, definitely check it out!</p><ul><li>🌟 <strong>Star Vrite on GitHub</strong> — <a href="https://github.com/vriteio/vrite">https://github.com/vriteio/vrite</a></li><li>🐞 <strong>Report bugs</strong> — <a href="https://github.com/vriteio/vrite/issues">https://github.com/vriteio/vrite/issues</a></li><li>🐦 <strong>Follow on Twitter</strong> — <a href="https://twitter.com/vriteio">https://twitter.com/vriteio</a></li><li>💬 <strong>Join Vrite Discord</strong> — <a href="https://discord.gg/yYqDWyKnqE">https://discord.gg/yYqDWyKnqE</a></li><li>ℹ️ <strong>Learn more about Vrite</strong> — <a href="https://vrite.io/">https://vrite.io</a></li><li>📕 <strong>Vrite documentation</strong> — <a href="https://docs.vrite.io/">https://docs.vrite.io</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=39e97f86e34" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Solid.js, React, and Vue — reactivity systems compared]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://areknawo.medium.com/solid-js-react-and-vue-reactivity-systems-compared-a36f9dfbfe9f?source=rss-703e187f4ea2------2"><img src="https://cdn-images-1.medium.com/max/1770/1*SdCimz3rIlkFMJGbyrftVQ.png" width="1770"></a></p><p class="medium-feed-snippet">All JavaScript UI frameworks work differently under-the-hood&#x200A;&#x2014;&#x200A;especially when it comes to reactivity&#x2026;</p><p class="medium-feed-link"><a href="https://areknawo.medium.com/solid-js-react-and-vue-reactivity-systems-compared-a36f9dfbfe9f?source=rss-703e187f4ea2------2">Continue reading on Medium »</a></p></div>]]></description>
            <link>https://areknawo.medium.com/solid-js-react-and-vue-reactivity-systems-compared-a36f9dfbfe9f?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/a36f9dfbfe9f</guid>
            <category><![CDATA[vuejs]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[web-framework]]></category>
            <category><![CDATA[solidjs]]></category>
            <category><![CDATA[react]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Sun, 29 Jan 2023 18:48:40 GMT</pubDate>
            <atom:updated>2023-01-29T18:48:40.765Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[Fixing Class Composition in Tailwind CSS]]></title>
            <link>https://areknawo.medium.com/fixing-class-composition-in-tailwind-css-f7c34530e422?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/f7c34530e422</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[tailwind-css]]></category>
            <category><![CDATA[web-design]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Wed, 14 Dec 2022 21:13:08 GMT</pubDate>
            <atom:updated>2022-12-14T21:29:21.090Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OYKuB3qcLBCpacRAA_60QA.jpeg" /></figure><p>I’ve been going <a href="https://areknawo.com/my-mixed-feelings-about-tailwind-css/">back</a> and <a href="https://areknawo.com/tailwind-jsx-and-class-composition/">forth</a> on <a href="https://tailwindcss.com/"><strong>Tailwind CSS</strong></a> for quite a while. On one hand, I loved the utility-first design, on the other — I hated how my HTML, JSX, etc. was getting bloated by the number of class names required to style even a basic button.</p><p>At last, Tailwind has won me over, mainly because it gets rid of one of the things I struggle with the most when writing CSS — <strong>naming</strong>. After all, as if designing good UI/UX wasn’t hard enough, you still have to find a good and architecturally-sound way to name all your classes — something that, for me at least, wasn’t achievable in the long run — no matter how many different CSS methodologies I tried.</p><p>On top of that, after using Tailwind for over a year now, for various projects, I found that it boosted my productivity. When paired with component-based framework utility classes work really well, especially when you have all of them memorized already. There is one caveat though…</p><h3>Class Composition</h3><p>Composing Tailwind’s utility classes is hard.</p><p>Consider you’re building an entire UI with basic components already having their styles defined through a set of Tailwind classes. What happens when you want to slightly alter the component just for a single use case? You can’t apply m-0 class because m-1 which the component already has applied, has higher specificity.</p><p>There are <a href="https://github.com/tailwindlabs/tailwindcss/discussions/1446">many opinions</a> on how to deal with such cases. Some recommend using the @apply directive for your components’ base styles. Others argue that you should already consider all the possible variants of your component and use JavaScript logic to apply proper classes based e.g. on the component’s props.</p><p>For me, both of those solutions feel like compromises. I don’t like using @apply unless it’s absolutely necessary. On the other hand, thinking of all the variants ahead of time or including all of them in the base component either limits your designs or overuses client-side JS.</p><p>There are a couple of third-party solutions to this problem though.</p><h3>Existing Alternatives</h3><p>The thing is pretty much all existing solutions involve using more client-side JS. Thus, while they’re more developer-friendly than e.g. concatenating utility classes by hand, they somewhat unnecessarily slow down your website.</p><p>I’ve already covered some of the more JS-heavy alternatives in <a href="https://areknawo.com/tailwind-jsx-and-class-composition/">one of my previous posts</a> — most, if not all of them are still actively maintained. For this article, I’ll focus more on the alternatives with limited use of JS and those I’ve newly discovered.</p><h4>twin.macro</h4><p>One of the more promising alternatives is <a href="https://github.com/ben-rogerson/twin.macro">twin.macro</a> — a <a href="https://github.com/kentcdodds/babel-plugin-macros">Babel macro</a> that processes Tailwind classes to generate JS objects understandable by various CSS-in-JS libraries. The developer experience (DX) of using it is amazing as you not only get all of Tailwind’s features without much change to your code, but you also get much more flexibility — all that on top of the traditional benefits of CSS-in-JS. Here’s an example code:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/84f6164a04403d243f33e2cd00064edc/href">https://medium.com/media/84f6164a04403d243f33e2cd00064edc/href</a></iframe><p>The problem is, twin.macro, while doing some processing during the build, still adds a lot of client-side JS — both by requiring a CSS-in-JS engine as well as putting all the style objects created through the macro into your JS code. This means not only slower performance, but also larger bundle sizes.</p><p>While twin.macro provided the best DX by far, there are a couple of other alternatives that got close to it, without adding as much additional JS code.</p><h4>Vanilla-extract</h4><figure><img alt="Windi CSS landing page" src="https://cdn-images-1.medium.com/max/1024/1*LT6kFG4iHHy1GKTJH54nFw.png" /><figcaption>Vanilla-extract landing page</figcaption></figure><p><a href="https://vanilla-extract.style/">Vanilla-extract</a> allows you to utilize TypeScript as your CSS preprocessor, just like Sass. On top of that, it comes with <a href="https://vanilla-extract.style/documentation/packages/sprinkles/">Sprinkles</a> — an atomic CSS framework that allows you to reproduce Tailwind’s utility classes.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/29ab177e7c28724f50425cd161be83b2/href">https://medium.com/media/29ab177e7c28724f50425cd161be83b2/href</a></iframe><p>The TS stylesheets must be defined in separate .css.js or .css.ts files though for “zero-runtime” usage. With that said, in order to achieve truly zero-runtime usage, you can only use Sprinkles in other TS stylesheets. This somewhat limits your flexibility.</p><p>Although you can use Sprinkles directly in your JS/TS code, a small runtime will be required — a helper function and a mapping object containing all your atomic classes, necessary for class lookup at runtime.</p><p>If you want to reproduce the entire set of utility classes from Tailwind, this object will be huge.</p><h4>Windi CSS</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zLU46XHfqcgXjAg2nNS7Tg.png" /><figcaption>Windi CSS landing page</figcaption></figure><p><a href="https://windicss.org/">Windi CSS</a> is a direct Tailwind alternative (with full Tailwind CSS v2 feature compatibility), with easier setup and faster compile times. While the advantages of this framework lessened as Tailwind matured to v3, its most promising feature (in regards to class composition) was a <strong>compilation mode</strong>. It was meant to compile utility classes applied on elements into singular, scoped classes.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/fb4e05f4b53bfaad91f575ec95599ec6/href">https://medium.com/media/fb4e05f4b53bfaad91f575ec95599ec6/href</a></iframe><p>If implemented well, this approach could fix all the issues related to class composition, while still providing DX similar to that of Tailwind. The only downside would be that, as described, it’d be an all-in or all-out solution that doesn’t allow you to pick which utility classes to “compile” and which to leave as is — leading to possibly large CSS bundles.</p><p>Still, this is by far the solution with the least negative impact. The only problem is, the development of the compile mode seems to have gone stale, leaving it available only to a few of Windi CSS dedicated integrations and <a href="https://windicss.org/posts/modes.html#compilation-mode">barely documented</a>. What’s worse, over the last few months development on the entire Windi CSS project has slowed down.</p><h3>Zero-runtime solution</h3><p>After exploring all the above alternatives (and more), I’ve decided to implement my own, custom solution. For that, I’ve turned to <a href="https://linaria.dev/">Linaria</a> — a true zero-runtime CSS-in-JS library.</p><figure><img alt="Linaria landing page" src="https://cdn-images-1.medium.com/max/1024/1*EVFcs1pcFUgtFaSCrbbCGQ.png" /><figcaption>Linaria landing page</figcaption></figure><p>After Linaria does its processing in the build step, all you get is just a string in JS, while the actual styling is extracted into a dedicated CSS file. On top of that, it integrates well with most preprocessors, such as Sass or PostCSS — together with the PostCSS Tailwind plugin.</p><p>Thanks to that, using Linaria, I was able to get something like the following:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/2ce3d91a326001b1fcd7052c67e04e74/href">https://medium.com/media/2ce3d91a326001b1fcd7052c67e04e74/href</a></iframe><p>With Linaria and JSX I got my entire component — including styles and structure — in one file, while not sacrificing performance or code quality. The only problem left is with the syntax.</p><p>While not too long, <em>css`@apply</em> is a lot to repeat for every class you want to “compile”. That’s why using <a href="https://vitejs.dev/">Vite</a> and some <a href="https://rollupjs.org/">Rollup</a> plugins (Vite uses Rollup under the hood) I was able to shorten it into this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/37aac5d3e1ea3c8590cecca52c8e8c30/href">https://medium.com/media/37aac5d3e1ea3c8590cecca52c8e8c30/href</a></iframe><p>With no need for any additional imports and tw template literal tag syntax (inspired by twin.macro), this became my go-to solution for all projects using Tailwind.</p><p>To summarize the advantages of this solution over previous alternatives:</p><ul><li>Opt-in class name “compilation”;</li><li>Truly zero-runtime (just strings);</li><li>Still using Tailwind under the hood (with all its utility classes and access to the latest updates);</li><li>Great DX (compact syntax, autocomplete in VS Code just by adjusting the regex in the Tailwind extension);</li></ul><p>There is one drawback though — the setup. Linaria, while amazing in its functionality, turns out to be quite problematic to install, even with the available guides and integrations. I’ve almost always run into issues when setting it up in a new project. On top of that, if you want the shorthand tw-based syntax, you need some additional configuration as well:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/45a8563ba9378fef804442a10b990922/href">https://medium.com/media/45a8563ba9378fef804442a10b990922/href</a></iframe><p>The above config is what I used to get the shorthand and Liniaria working in Vite. To give you an overview of how it works — the tw\`` is first replaced with css`@applyand then thecss` template literal tag is auto-imported where necessary. I’ve only used this setup with Vite and <a href="https://astro.build/">Astro</a> (Vite-based) so I don’t know how hard it’d be to get it working in other bundlers (though pure Rollup should work as well).</p><p>Because of such a difficult setup and all the potential bug-fixing involved, it’s not something I’d recommend for everyone. With that said, I’m willing to go through it, just to later enjoy good DX, performant styling, and easy class composition. I haven’t yet explored extracting the entire setup into a separate Vite plugin, but it might be worth considering.</p><h3>UnoCSS — the newest alternative</h3><p>Now, I’d like to mention one more Tailwind alternative that might be worth your attention — especially in regards to class composition — <a href="https://uno.antfu.me/">UnoCSS</a>.</p><figure><img alt="UnoCSS landing page" src="https://cdn-images-1.medium.com/max/1024/1*B-zqDVzuKPacbV2J3Sl81g.png" /><figcaption>UnoCSS landing page</figcaption></figure><p>UnoCSS seems to be the spiritual successor of Windi CSS, sharing some of its features and contributors. It’s an atomic CSS engine, meaning that it allows you to create your own utility CSS frameworks on top of it. Additionally, it’s super-fast, thanks partially to its architecture but also its general simplicity.</p><p>The best thing about UnoCSS is that it looks to be the best tool for atomic CSS, with various presets for defining utility classes (including one for Tailwind CSS) and great features, that can’t be found in Tailwind — including <strong>compilation mode</strong>!</p><p>That’s right, UnoCSS has a compilation mode, that’s even better than what was originally intended for Windi CSS, as it’s opt-in (with a configurable prefix), meaning you only compile the class names that you want!</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/4faf052c373085b8befe7de9fa40725f/href">https://medium.com/media/4faf052c373085b8befe7de9fa40725f/href</a></iframe><p>UnoCSS seems like the go-to option to replace my scrappy setup. It’s working really well in my initial experiments and, in the future, I’ll likely move some, if not all, of my projects to UnoCSS.</p><h3>Conclusion</h3><p>This post is a result of a year or two of research, experimentation, and actual usage of different tools in various projects of mine. It didn’t even cover all alternatives I tested nor what’s possible with the likes of UnoCSS and other, “bleeding-edge” solutions. With that said, if you’re dealing with class composition and are in search of great development experience, I hope you found this article helpful!</p><h3>Vrite</h3><p><strong>Blogging for developers</strong> | <em>coming 2023</em><br>Join the waitlist now 👉 <a href="https://vrite.io/">https://vrite.io</a></p><p>Professional editor and powerful headless CMS in one. Vrite is a writing platform by developers, for developers.</p><figure><img alt="Vrite landing page" src="https://cdn-images-1.medium.com/max/1024/1*yvSoNY_vxPKrjb8jY6n9xA.png" /><figcaption>Vrite landing page</figcaption></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f7c34530e422" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Top 6 Heroku alternatives]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://areknawo.medium.com/top-6-heroku-alternatives-8aa31b73475c?source=rss-703e187f4ea2------2"><img src="https://cdn-images-1.medium.com/max/2600/0*KjCR6UqYS2Th4Bra" width="4256"></a></p><p class="medium-feed-snippet">Heroku has announced that on November 28th, 2022, it&#x2019;ll stop providing free tiers of products like Dynos or Postgres. For a while now&#x2026;</p><p class="medium-feed-link"><a href="https://areknawo.medium.com/top-6-heroku-alternatives-8aa31b73475c?source=rss-703e187f4ea2------2">Continue reading on Medium »</a></p></div>]]></description>
            <link>https://areknawo.medium.com/top-6-heroku-alternatives-8aa31b73475c?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/8aa31b73475c</guid>
            <category><![CDATA[backend]]></category>
            <category><![CDATA[heroku]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[firebase]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Sat, 19 Nov 2022 00:28:32 GMT</pubDate>
            <atom:updated>2022-11-19T00:28:32.711Z</atom:updated>
        </item>
        <item>
            <title><![CDATA[React 18: Feature Breakdown]]></title>
            <description><![CDATA[<div class="medium-feed-item"><p class="medium-feed-image"><a href="https://medium.com/stackanatomy/react-18-feature-breakdown-bd0d4e9af76c?source=rss-703e187f4ea2------2"><img src="https://cdn-images-1.medium.com/max/2401/1*fcIGwY0AGvX2JsjArNGt4A.png" width="2401"></a></p><p class="medium-feed-snippet">All the new features in React 18, with an analysis of their impact.</p><p class="medium-feed-link"><a href="https://medium.com/stackanatomy/react-18-feature-breakdown-bd0d4e9af76c?source=rss-703e187f4ea2------2">Continue reading on StackAnatomy »</a></p></div>]]></description>
            <link>https://medium.com/stackanatomy/react-18-feature-breakdown-bd0d4e9af76c?source=rss-703e187f4ea2------2</link>
            <guid isPermaLink="false">https://medium.com/p/bd0d4e9af76c</guid>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[react]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Arek Nawo]]></dc:creator>
            <pubDate>Thu, 19 May 2022 12:19:01 GMT</pubDate>
            <atom:updated>2022-05-29T19:23:35.786Z</atom:updated>
        </item>
    </channel>
</rss>