<?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 Cecylia Borek on Medium]]></title>
        <description><![CDATA[Stories by Cecylia Borek on Medium]]></description>
        <link>https://medium.com/@cecylia.borek?source=rss-222334e0dddc------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*VPAhaZwiCUtQXkMz</url>
            <title>Stories by Cecylia Borek on Medium</title>
            <link>https://medium.com/@cecylia.borek?source=rss-222334e0dddc------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 11:57:12 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@cecylia.borek/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[The best AI tools for generating websites in 2025]]></title>
            <link>https://medium.com/@cecylia.borek/the-best-ai-tools-for-generating-websites-in-2025-a828696806ab?source=rss-222334e0dddc------2</link>
            <guid isPermaLink="false">https://medium.com/p/a828696806ab</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[website-design]]></category>
            <category><![CDATA[ai-website-generator]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Cecylia Borek]]></dc:creator>
            <pubDate>Mon, 17 Feb 2025 17:25:37 GMT</pubDate>
            <atom:updated>2025-02-17T17:25:37.111Z</atom:updated>
            <content:encoded><![CDATA[<p>Recently, I had to create a simple website for a charity run. The requirements were quite straightforward: a simple one page site with basic information about the run, a map of the course, and a sign up form. I decided to explore AI-powered tools to generate the website, and here’s a quick rundown of what I found.</p><blockquote><em>For all the tools I tested, I used a prompt similar to this as a starting point: </em>Create a website for a charity run. The website should include basic info about the race, map of the course and a sign up form. The style should be modern, minimalistic, easy to use, illustration-like, fun.</blockquote><h3>False Starts: What didn’t work</h3><p>At this point, all major website development sites like <a href="https://www.wix.com/">Wix</a>, <a href="https://www.framer.com/">Framer</a>, etc., claim to have an AI website builder. However, I was quite disappointed with most of them. Those AI generators would mostly use one of the site’s predefined templates and only add content matching my prompt. Considering the fact that those services are optimised for creating e-commerce and generic online business websites, they really did not do a good job for my case.</p><p>As an example, website generated by <em>codedesign.ai</em> — it looks cool, but very generic (typical online business) and definitely not aligned with my prompt.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/865/1*yc_fV_i0NhjvX6hjwGGiKA.png" /><figcaption>Website generated by codedesign.ai</figcaption></figure><p>When it comes to Wix, the website didn’t even look cool — it was very blant and old looking:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rqEmWCry2tHXB9S3Pu23zA.png" /><figcaption>Website generated by Wix</figcaption></figure><p>One additional drawback of using website generators from services like Wix is that you are bound to the platform. You cannot easily export the site and host it somewhere else.</p><p>Now, let’s move to the tools which I found helpful, and will definitely be using again!</p><h3>StarryAI</h3><p><a href="https://starryai.com/">StarryAI</a> is an AI art generator. You can create a free account and claim five free credits each day to generate art (1 credit = 1 image).</p><p><strong>My rating</strong>: 3/5</p><h4>Pros</h4><ul><li>you can buy credits or a monthly subscription — I like the flexibility of not having to buy a subscription</li><li>generates really cool pieces</li><li>you can create a custom <em>style</em> in which the art should be generated</li><li>generates multiple versions of the design</li><li>generous free offer (new free credits each day, possibility to earn credits by sharing on social media, etc.)</li></ul><h4>Cons</h4><ul><li>it’s an art generator so it doesn’t generate source code</li><li>doesn’t allow iterative design — no chatting with AI to refine and align the design</li><li>not tailored for websites specifically — the created designs look more like posters and may not follow web design practices</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/912/1*Rjq-O6MhYBPWjmhIP5oiew.jpeg" /><figcaption>Website design generated by StarryAI</figcaption></figure><h3>JIT</h3><p><a href="https://jit.dev/">JIT</a> is an AI-powered coding platform, which allows you to generate code in several languages. You can pick which LLM should be used for the generation (gpt-4o, gpt-4o-mini, DeepSeek, claude-3–5-sonnet).</p><p><strong>My rating</strong>: 3.5/5</p><h4>Pros</h4><ul><li>generates source code</li><li>easy to host the website since the generated code is in HTML/CSS/JavaScript</li><li>unlimited public code generations in the free tier</li><li>allows iterative design process</li><li>possibility to buy either credits or a monthly subscription</li><li>possibility to pick the underlying model</li><li>low price for the Pro version — $3.49/ month</li></ul><h4>Cons</h4><ul><li>not very refined yet — sometimes inserts model’s “thinking process” into the source code, some parts of the generated website lack styling, etc.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MQl1uItz4NtVOKO-vIfGEQ.png" /><figcaption>Website generated by JIT with DeepSeek R1</figcaption></figure><h3>Bolt.new</h3><p><a href="https://bolt.new/">Bolt.new</a> is an AI web development agent by StackBlitz that, unsurprisingly for StackBlitz, runs in the browser. It supports building apps using different frameworks and libraries (like Astro, Tailwind, ShadCN, or any other popular JavaScript framework) and gives the AI agent full control over the dev environment (filesystem, node server, package manager, terminal, and browser console).</p><p><strong>My rating</strong>: 5/5</p><h4>Pros</h4><ul><li>100K free tokens per month</li><li>generates source code in modern JavaScript frameworks and libraries</li><li>allows iterative design process</li><li>creates whole development environment in the browser</li><li>high quality of outputs</li></ul><h4>Cons</h4><p>Couldn’t find any for my use case. Definitely my favourite!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*v8TcedpDJj-Yy0N1-ouWhg.png" /><figcaption>Website generated by bolt.new</figcaption></figure><h3>v0 by Vercel</h3><p><a href="https://v0.dev/">v0</a> is Vercel’s <em>Generative UI. </em>It produces code using open-source tools like React, Tailwind CSS, and <a href="https://ui.shadcn.com/">Shadcn UI</a>. The free plan includes 200 credits per month.</p><p><strong>My rating</strong>: 3.5/5</p><h4>Pros</h4><ul><li>generates source code in React and Tailwind</li><li>allows iterative design process</li><li>high quality of outputs</li></ul><h4>Cons</h4><ul><li>strongly tied to NextJS and Vercel</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/993/1*7EGder8lmJzN-ylKMEoe8A.png" /><figcaption>Website generated by v0</figcaption></figure><h3>Galileo AI</h3><p><a href="https://www.usegalileo.ai/explore">Galileo AI</a> is an AI UI generation platform. Users receive 150 free credits, which allow generating 15 designs. The designs can be exported to Figma or source code (HTML + Tailwind).</p><p><strong>My rating</strong>: 4/5</p><h4>Pros</h4><ul><li>allows exporting designs to Figma and source code (HTML + Tailwind)</li><li>allows iterative design process</li><li>tailored to creating UI designs</li><li>high quality of outputs</li></ul><h4>Cons</h4><ul><li>can either generate mobile or web design, didn’t generate responsive design</li><li>quite limited free tier compared to other tested tools</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/648/1*cIbZ1Jqia81u-OsIl2kiJQ.png" /><figcaption>Website generated by Galileo AI</figcaption></figure><h3>Summary</h3><p>Trying out these tools was both fun and surprisingly productive! For a simple website like mine, the results were impressive — just a few minor tweaks, and it was ready to deploy. I believe these tools could also serve as great starting points for more advanced websites. I’ll definitely be using them again in the future!</p><p>If you know of any other AI tools for website creation and design, drop them in the comments — I’d love to check them out!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a828696806ab" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a Testing Framework from Scratch with Node.js and TypeScript]]></title>
            <link>https://medium.com/@cecylia.borek/building-a-testing-framework-from-scratch-with-node-js-and-typescript-2709a8041f16?source=rss-222334e0dddc------2</link>
            <guid isPermaLink="false">https://medium.com/p/2709a8041f16</guid>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[testing-framework]]></category>
            <category><![CDATA[testing]]></category>
            <dc:creator><![CDATA[Cecylia Borek]]></dc:creator>
            <pubDate>Mon, 16 Dec 2024 14:50:27 GMT</pubDate>
            <atom:updated>2024-12-17T08:34:50.385Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BFOUSiO9i5PfFAvbuv5rNg.png" /></figure><p>Welcome back to <em>Spectacular</em>, a simple testing framework created for fun using Node.js and TypeScript! In this blog post series, I’m documenting the entire journey of building a testing framework from scratch. Today, in part 2, we’ll focus on the basic functionalities of a testing framework.</p><p>If you missed part 1, where I discussed what a monorepo is and how I’m using it for this project, <a href="https://medium.com/@cecylia.borek/setting-up-a-monorepo-using-npm-workspaces-and-typescript-project-references-307841e0ba4a">be sure to check it out</a>. Alternatively, if you’d like to jump straight into today’s setup, you can copy it from <a href="https://github.com/cecyliaborek/spectacular/tree/part-1-monorepo-ts">GitHub</a>.</p><blockquote>I am creating Spectacular in Node.js and TypeScript and using npm. If you want to follow along make sure you have Node.js and npm on your machine.</blockquote><blockquote>If you want to use the same setup as me, you can read the <a href="https://medium.com/@cecylia.borek/setting-up-a-monorepo-using-npm-workspaces-and-typescript-project-references-307841e0ba4a">part 1 in the series about setting up the monorepo</a> or copy the setup from <a href="https://github.com/cecyliaborek/spectacular/tree/part-1-monorepo-ts">GitHub</a>.</blockquote><h3>The goal</h3><p>The goal of this part of the project is to implement the core functionality of a testing framework. By the core functionality I mean:</p><ul><li>creating and running testcases</li><li>asserting the actual results with expected ones.</li></ul><p>Let’s do it!</p><h3>The basics of a test framework</h3><p>This might be a bit embarrassing, but at first I wasn’t sure how to start writing a testing framework. For some of you, this might be easy-peasy, but I was a bit stuck. If you’re in a similar situation, let’s think about it. How does a test file look like in a typical testing framework?</p><pre>// example test file in vitest<br><br>import { expect, test } from &#39;vitest&#39;<br>import { sum } from &#39;./sum.js&#39;<br><br>test(&#39;adds 1 + 2 to equal 3&#39;, () =&gt; {<br>  expect(sum(1, 2)).toBe(3)<br>})</pre><p>A test file, like the above from vitest, contains test cases (in most frameworks denoted with test() or it()). Inside a test case, the expect() function, together with different matchers (toBe(), toEqual, etc.), is used to compare the actual and expected results of a tested functionality.</p><h3>test()</h3><p>Looking at the test() , we realize that it is a simple function which takes two arguments:</p><ul><li>a string, which is a name of the test case</li><li>and a callback, which is the actual test.</li></ul><p>With that in mind, we can implement a test() function.</p><blockquote>I will be putting the code for basic (core) functionality into the core package — <em>packages/core/src</em>. If you want to learn more about how I structured my project and why, head out to the <a href="https://medium.com/@cecylia.borek/setting-up-a-monorepo-using-npm-workspaces-and-typescript-project-references-307841e0ba4a">part 1 of the spectacular blog-post series</a>!</blockquote><pre>// packages/core/src/index.ts<br><br>export function test(name: string, callback: () =&gt; void): void {<br>  try {<br>    callback();<br>    console.log(`✓ ${name}`);<br>  } catch (error) {<br>    console.log(`✕ ${name}`);<br>    console.log(error);<br>  }<br>}</pre><p>As mentioned, the test() function takes two arguments: a name and a callback. It executes the callback inside a try-catch block. If the callback runs without any errors, we assume the test has passed (let’s keep that in mind for later, this will be needed when we are implementing expect()). We are logging to the console the test case name with a little tick ✔️ as an indication that it passed. If the callback throws any errors, we are printing them and the name of the test case with a cross ❌, as an indication of a failed test.</p><h3>expect()</h3><p>Now, let’s move to the expect(). It takes the actual result of a tested functionality and then… we can chain different matchers to it. In javascript that means expect() should return an object with matcher functions. Some of the matchers take an argument of the expected value (e.g. toEqual(expected), toBe(expected)) and some don’t (toExist(), toBeNull()). The matchers should assert the actual value with the expected result - with rules of those assertions depending on a given matcher.</p><p>For example, the toBe() matcher should compare the actual value with the expected value. If the values are different, it can throw an error with an appropriate message (remember how we implemented the test() function? it was executing the callback, which will contain the expect() function, inside a try-catch block - and assuming that the test passes if no errors were thrown, fails otherwise). toExist() should just check if the <em>actual</em> value is defined and throw an error otherwise. And so on for the other matchers. We end up with the expect() function looking something like this:</p><pre>// packages/core/src/index.ts<br><br>function expect(actual) {<br>  return {<br>    toBe(expected) {<br>      if (actual !== expected) {<br>        throw new Error(`${actual} is not equal to ${expected}`);<br>      }<br>    },<br>    toEqual(expected) {<br>      if (actual != expected) {<br>        throw new Error(`${actual} is not equal to ${expected}`);<br>      }<br>    },<br>    toExist() {<br>      if (actual === undefined) {<br>        throw new Error(`${actual} is not defined`);<br>      }<br>    },<br>    // add more matchers<br>  };<br>}</pre><p>There is one problem with the above implementation in typescript: actual has explicitly any type. But we don’t know what the type of <em>actual</em> and <em>expected</em> will be, and we want it to work for different types. The answer to solve this issue is <em>generics</em>. Generics is a larger topic for another discussion (<a href="https://www.typescriptlang.org/docs/handbook/2/generics.html">typescript documentation about generics</a>, <a href="https://www.freecodecamp.org/news/how-typescript-generics-work/">freeCodeCamp article explaining generics</a>), but to summarize it very shortly, according to typescript’s documentation:</p><blockquote><strong>Generics</strong><em>, </em>that is, being able to create a component that can work over a variety of types rather than a single one.</blockquote><p>And this is exactly what we need! The expect() function should be flexible and handle any type of input. However, we still want to maintain type safety so that the types of expected and actual are the same (because it makes no sense to compare values of different types). To make the expect function generic, we provide a type parameter <em>T</em> in the function’s declaration.</p><pre>function expect&lt;T&gt;(...) { ... }</pre><p>Then we can specify the types of actual and expected to be <em>T.</em></p><pre>function expect&lt;T&gt;(actual: T) { <br>	return {<br>	    toBe(expected: T) { ... },<br>	    ... <br>	  };<br> }</pre><p>With these, whenever the expect() function will be used, we can either explicitly provide the type, e.g. :</p><pre>// Here you specify T explicitly<br>expect&lt;number | null&gt;(null).toExist();</pre><p>or if you don’t provide the type, typescript will infer the type:</p><pre>// TypeScript infers that T is &#39;number&#39; from the argument &#39;5&#39;<br>expect(5).toBe(5);   // No need to specify &lt;number&gt;</pre><p>In both cases type safety of the comparisons is enforced at compile time, which helps avoid runtime errors due to type mismatches.</p><p>This is the final look of the generic expect() function:</p><pre>// packages/core/src/index.ts<br><br>function expect&lt;T&gt;(actual: T) {<br>  return {<br>    toBe(expected: T) {<br>      if (actual !== expected) {<br>        throw new Error(`${actual} is not equal to ${expected}`);<br>      }<br>    },<br>    toEqual(expected: T) {<br>      if (actual != expected) {<br>        throw new Error(`${actual} is not equal to ${expected}`);<br>      }<br>    },<br>    toExist() {<br>      if (actual === undefined) {<br>        throw new Error(`${actual} is not defined`);<br>      }<br>    },<br>  };<br>}</pre><h3>To be or not to be</h3><p>Another useful operator that can be chained to expect() is the not operator. It simply negates the result of the matcher that follows it.</p><pre>expect(input).not.toBe(2); // checks if the input is NOT equal to 2</pre><p>How can we implement it?</p><p>not can be chained to expect and it will negate all the assertions. If not isn’t used, the assertions won’t be negated. We can depict it like that:</p><pre>function expect&lt;T&gt;(actual: T) {<br>  return {<br>	  not: { // negated matchers },<br>	  { // &quot;original&quot; matchers }<br>  };<br>}</pre><p>In other words, expect now returns an object, which has an additional property - not - which will have the negated matchers as its value. All the other properties (so the “original”, “unnegated” matchers) stay the same. Let’s now complete the implementation. Since we now need matchers in two places, we can create a helper function to create negated or unnegated matchers:</p><pre>// packages/core/src/index.ts<br><br>function getMatchers&lt;T&gt;(negated: boolean, actual: any) {<br>  return {<br>    toBe(expected: T) {<br>      const result = actual === expected;<br>      if (negated ? result : !result) {<br>        throw new Error(`${actual} is not equal to ${expected}`);<br>      }<br>    },<br>    toEqual(expected: T) {<br>      const result = actual == expected;<br>      if (negated ? result : !result) {<br>        throw new Error(<br>          negated<br>            ? `${actual} is equal to ${expected}`<br>            : `${actual} is not equal to ${expected}`<br>        );<br>      }<br>    },<br>    toExist() {<br>      const result = actual !== undefined;<br>      if (negated ? result : !result) {<br>        throw new Error(<br>          negated ? `${actual} is defined` : `${actual} is not defined`<br>        );<br>      }<br>    },<br>    toBeNull() {<br>      const result = actual === null;<br>      if (negated ? result : !result) {<br>        throw new Error(<br>          negated ? `${actual} is null` : `${actual} is not null`<br>        );<br>      }<br>    },<br>  };<br>}<br><br>export function expect&lt;T&gt;(actual: T) {<br>  return {<br>    not: {<br>      ...getMatchers(true, actual),<br>    },<br>    ...getMatchers(false, actual),<br>  };<br>}</pre><p>If you want, you can play around and add more matchers!</p><h3><em>Testing</em> it out</h3><p>At this point, the basic core functionality of the testing framework should be ready. We can create a simple test case in the <em>monthy-python</em> package and use our newly created functions. In <em>packages/monthy-python/src/index.js,</em> let’s write:</p><pre>// packages/monthy-python/src/index.js<br><br>const { test, expect } = require(&quot;@spectacular/core/dist/index.js&quot;);<br><br>test(&quot;first spectacular test case&quot;, () =&gt; {<br>  expect(1).toBe(1);<br>});</pre><p>If you are using my monorepo setup, you can run the <em>monthy-python </em>package with:</p><pre>npm start -w @spectacular/monthy-python</pre><p>Otherwise, you can just run the file in which you have written the test case with node.</p><p>If everything goes fine, this is the result we are getting:</p><pre>✓ first spectacular test case</pre><p>Yay! The first spectacular test case passed! 🎉</p><p>We can also try to write a failing test:</p><pre>// packages/monthy-python/src/index.js<br><br>const { test, expect } = require(&quot;@spectacular/core/dist/index.js&quot;);<br><br>test(&quot;first spectacular test case&quot;, () =&gt; {<br>  expect(1).toBe(1);<br>});<br>test(&quot;should fail&quot;, () =&gt; {<br>  expect(2).toBe(3);<br>});</pre><p>And the result, as <em>expected</em> is:</p><pre>✓ first spectacular test case<br>✕ should fail<br>Error: 2 is not equal to 3<br>    at Object.toBe (/Users/cecyliaborek/All/Code/spectacular/packages/core/dist/index.js:19:23)<br>    at /Users/cecyliaborek/All/Code/spectacular/packages/monthy-python/src/index.js:8:13<br>    at test (/Users/cecyliaborek/All/Code/spectacular/packages/core/dist/index.js:7:9)<br>    at Object.&lt;anonymous&gt; (/Users/cecyliaborek/All/Code/spectacular/packages/monthy-python/src/index.js:7:1)<br>    at Module._compile (node:internal/modules/cjs/loader:1241:14)<br>    at Module._extensions..js (node:internal/modules/cjs/loader:1295:10)<br>    at Module.load (node:internal/modules/cjs/loader:1091:32)<br>    at Module._load (node:internal/modules/cjs/loader:938:12)<br>    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:83:12)<br>    at node:internal/main/run_main_module:23:47</pre><h3>We’re done! 🙌🏻</h3><p>Well done for completing part 2 of the S<em>pectacular</em> blogpost series! If you want, you can see the complete code for this part on <a href="https://github.com/cecyliaborek/spectacular/tree/part-2-basic-functionality">GitHub</a>.</p><p>Stay tuned for the next parts coming soon! Next up, we will be running all tests within a project with a single command.</p><p>If you missed it, be sure to check <a href="https://medium.com/@cecylia.borek/setting-up-a-monorepo-using-npm-workspaces-and-typescript-project-references-307841e0ba4a">part 1 of the series</a>, all about monorepos, monorepo tools, and how I’m using them!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2709a8041f16" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Setting up a monorepo using npm workspaces and TypeScript Project References]]></title>
            <link>https://medium.com/@cecylia.borek/setting-up-a-monorepo-using-npm-workspaces-and-typescript-project-references-307841e0ba4a?source=rss-222334e0dddc------2</link>
            <guid isPermaLink="false">https://medium.com/p/307841e0ba4a</guid>
            <category><![CDATA[npm-workspaces]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[monorepo]]></category>
            <dc:creator><![CDATA[Cecylia Borek]]></dc:creator>
            <pubDate>Thu, 05 Dec 2024 13:35:07 GMT</pubDate>
            <atom:updated>2024-12-05T13:35:07.308Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*N-WHdWUG8yX4pkE3i-xW1w.png" /></figure><p>One day at work, I wanted to check how something works in <a href="https://www.notion.so/066cc8d2d061411284d5540bd12f7665?pvs=21">spectator</a> (a tool for simplifying writing tests in angular) and was looking at its source code. It was then that I got this great idea: why don’t I write my own testing framework? Before you start thinking what a nonsense idea it is, I want to make clear: obviously, I am not writing the next state-of-the-art testing framework. Of course I am not. My idea was to create a simple testing framework from scratch in order to learn something. A sort of hobby project if you will.</p><p>If you still think this is not a great idea, consider these.</p><p>Firstly, this is a great opportunity to learn something and improve your skills. The good old <em>learning by doing</em>. It is also always good to have a nice little project in your portfolio to brag about to potential future employees. And maybe you could even write a medium article about the project afterwards.</p><p>And that’s essentially how and why I decided to create my own testing framework, called s<em>pectacular</em>, using Node.js and TypeScript.</p><p>As with every fun project, my project grew after I started it. I got new ideas and encountered challenges while working on it. Therefore, this is part 1 of a mini-series, where I will focus solely on the setup for the project (I will explain shortly!).</p><p>More parts are coming (hopefully soon!) where I will be sharing how to implement the actual core functionalities of a testing framework, how to turn the framework into a command line tool or how I created --watch-mode for the framework. So stay tuned!</p><h3>The problem</h3><p>As mentioned in the intro, my project grew a lot once I started working on it. With the passing of time and development, I was constantly encountering new challenges. One of these was the setup for the project. At first, I created a simple Node.js + TypeScript project, but I soon ran into a problem: I was trying to build and use the testing framework inside the same repository (single node project). While it is technically possible, it creates a lot of confusion. After all, the intention of the framework is to use it in <em>other</em> projects. Moreover, my plan was to not only implement the core functionality of the testing framework but also a CLI (command line interface for the framework). While the CLI depends on the core functionality (it uses it to run the tests), the core doesn’t depend on the CLI. In fact, it is a completely standalone piece of the framework, which can be used on its own. That’s how I ended up with a project setup, which is a topic for a blog post on its own — a monorepo.</p><h3>Monorepo</h3><blockquote><em>A monorepo is a single repository containing multiple distinct projects, with well-defined relationships.</em></blockquote><p>The above is a definition of a monorepo from <a href="https://monorepo.tools/">monorepo.tools</a>. The projects of a monorepo are related, but logically independent and are often worked on by different teams. A single project of a monorepo can be either an application or a shared library. Libraries contain common functionality or UI components, which are used by the applications.</p><p>A common misconception is that a monorepo is a monolith. However, a good monorepo should actually be the opposite of a monolith. The below diagram from <a href="http://monorepo.tools/">monorepo.tools</a> depicts this well:</p><figure><img alt="A comparison between a monolith and a monorepo" src="https://cdn-images-1.medium.com/max/947/1*BkPf6-cMNXDuLTrkqG6_0Q.png" /><figcaption><a href="https://monorepo.tools/#what-is-a-monorepo">https://monorepo.tools/#understanding-monorepos</a></figcaption></figure><p>Many big companies are using monorepos for their projects. Google, for example, keeps most of its code — <a href="https://cacm.acm.org/research/why-google-stores-billions-of-lines-of-code-in-a-single-repository/">billion lines of it</a> — in a single repository (~90TB).</p><p>Some of the benefits of using a monorepo are:</p><ul><li>simplified core sharing — we have shared libraries directly in the repository</li><li>atomic commits — the developers have access to the whole codebase, so they can fix everything in the same commit</li><li>single source of truth — one version of each dependency prevents conflicts between different projects</li></ul><h3>The goal</h3><p>Now that we know the basics of what a monorepo is, we can define a goal for the project. We want to create a monorepo for <em>spectacular</em>, which for now will contain three different packages:</p><ul><li><em>core</em> — this will be the core functionality of the testing framework</li><li><em>cli</em> — everything related to the command line interface for the framework; this package depends on the <em>core</em></li><li><em>monthy-python</em> — this will be an example app which uses the the testing framework.</li></ul><h3>Npm workspaces</h3><p>To work with a monorepo, we will need some tools to help us manage it. There are many monorepo tools, such as <a href="https://nx.dev/">Nx</a>, <a href="https://github.com/vercel/turborepo?utm_source=monorepo.tools">turborepo</a>, <a href="https://github.com/bazelbuild/bazel?utm_source=monorepo.tools">bazel</a>, and more. They provide different features to help you manage your monorepo, like computation caching, codebase analysis, code generation, visualizations, constraints, etc.</p><p>However, for the simple use-case of the testing framework, our main objective is to simply divide the code into distinct projects in a single repository and handle their dependencies. For now (<em>did I ever mention how the projects keep growing while you work on them?</em>), we don’t need any of the fancy features those tools provide. Therefore, I decided to use <a href="https://docs.npmjs.com/cli/v10/using-npm/workspaces">npm workspaces</a>. We would have used npm for package management anyway — so we can avoid <a href="https://en.wikipedia.org/wiki/Overengineering">over-engineering</a>.</p><p>From npm documentation:</p><blockquote><strong><em>Workspaces</em></strong><em> is a generic term that refers to the set of features in the npm cli that provides support for managing multiple packages from your local file system from within a singular top-level, root package.</em></blockquote><p>In the npm terminology, a single <em>package</em> of a monorepo is often referred to as <em>workspace</em>. A single package of a monorepo is also often called a <em>project</em>. Therefore, for the rest of this post, the terms <em>package, workspace</em> and <em>project</em> will be used interchangeably.</p><p>Let’s see how it all works in practice!</p><h3>Initialising the project and the packages</h3><blockquote>Before we begin, make sure you have node and npm installed on your machine.</blockquote><p>Let’s start with creating a new folder for the root-level project (our monorepo) and initialising a node project inside it:</p><pre>mkdir spectacular <br>cd spectacular<br>npm init -y</pre><p>Next, we will use the <em>-w</em> option of npm to initialise a new <em>core </em>package inside our monorepo:</p><pre>npm init -y --scope @spectacular -w packages/core</pre><p>There are a few things this command does:</p><ul><li>creates the specified folder(s) packages/core if they don’t exist yet, and initialises the core workspace with package.json</li></ul><pre>.<br>├── package-lock.json<br>├── package.json<br>└── packages<br>    └── core<br>        └── package.json</pre><ul><li>adds workspaces field to the root package.json with a reference to the newly created <em>core </em>workspace (project)</li></ul><pre>{<br>  &quot;name&quot;: &quot;spectacular&quot;,<br>  &quot;version&quot;: &quot;1.0.0&quot;,<br>  ...<br>  &quot;workspaces&quot;: [<br>    &quot;packages/core&quot;,<br>  ],<br>}</pre><ul><li>creates a symlink of the new package inside the node_modules. A symlink is a symbolic link between a local package and your project so that you can use that local package (in this case @spectacular/core) in your project without the need to publish it to the npm registry</li></ul><pre>node_modules<br> └── @spectacular<br>     └── core -&gt; ../../packages/core</pre><ul><li>the --scope @spectacular option makes the <em>core </em>package scoped. If you’re interested, you can read more about scope in the <a href="https://docs.npmjs.com/cli/v9/using-npm/scope">npm’s documentation</a>. For now, it’s enough if you know that a scope is a way to group packages together - which makes sense for our case of multiple packages constituting the spectacular framework. It also means, that we should be referring to the package by its name, prepended with the scope name, like this: @spectacular/core.</li></ul><p>Similarly, let’s also add the <em>cli</em> and <em>monthy-python</em> packages:</p><pre>npm init -y --scope @spectacular -w packages/cli<br>npm init -y --scope @spectacular -w packages/monthy-python</pre><p>This is how the project structure should look afterwards:</p><pre>.<br>├── node_modules<br>│   └── @spectacular<br>│       ├── cli -&gt; ../../packages/cli<br>│       ├── core -&gt; ../../packages/core<br>│       └── monthy-python -&gt; ../../packages/monthy-python<br>├── package-lock.json<br>├── package.json<br>└── packages<br>    ├── cli<br>    │   └── package.json<br>    ├── core<br>    │   └── package.json<br>    └── monthy-python<br>        └── package.json<br></pre><h3>Defining dependencies</h3><p>Now that we have the basic structure of the monorepo, let’s add the dependencies between the packages. As mentioned earlier, our intended use case is for <em>cli</em> to depend on <em>core</em> and <em>monthy-python</em> to use (depend on) <em>cli</em>.</p><p>You can install a package as a dependency of another package using npm install. So, to add <em>core</em> as a dependency to <em>cli</em>, simply run:</p><pre>npm install @spectacular/core -w @spectacular/cli</pre><p>With the -w option here we are specifying to which workspace the dependency should be added.</p><p>This will update the package.json in the <em>cli </em>workspace:</p><pre>{<br>  &quot;name&quot;: &quot;@spectacular/cli&quot;,<br>  ...<br>  &quot;dependencies&quot;: {<br>    &quot;@spectacular/core&quot;: &quot;^1.0.0&quot;<br>  }<br>}</pre><p>Let’s also add <em>cli</em> as a dependency of <em>monthy-python</em>:</p><pre>npm install @spectacular/cli -w @spectacular/monthy-python</pre><h3>Testing it out</h3><p>Let’s create simple code in the packages and test if the setup works:</p><p>In packages/core/index.js</p><pre>console.log(&quot;Core package&quot;);</pre><p>In packages/cli/index.js</p><pre>require(&quot;@spectacular/core&quot;);<br>console.log(&quot;CLI package&quot;);</pre><p>In packages/monthy-python/index.js</p><pre>require(&quot;@spectacular/cli&quot;);<br>console.log(&quot;Monthly Python package&quot;);</pre><p>Running the core package (node packages/core/index.js) produces the following, expected result:</p><pre>Core package</pre><p>Running cli package (node packages/cli/index.js):</p><pre>Core package<br>CLI package</pre><p>And finally, running monthy-python:</p><pre>Core package<br>CLI package<br>Monthly Python package</pre><p>So everything works as expected and we can consume the separate npm projects from within each other in our monorepo. If you want, you can check out the <a href="https://github.com/cecyliaborek/spectacular/tree/part-1-monorepo-js">full source code for the current setup </a>— with npm workspaces and JavaScript.</p><h3>Adding TypeScript</h3><p>Because we want to write our project in TypeScript, let’s now convert the project from JavaScript to TypeScript.</p><p>For the <em>monthy-python</em> project, let’s keep using JavaScript (to make things easier for ourselves, <em>spectacular</em> will only support testing JavaScript for now). This is easy in the monorepo setup where all the projects are independent. Therefore, we will be only converting <em>core</em> and <em>cli</em> to TypeScript.</p><p>First things first, let’s add TypeScript as a dev dependency into the root workspace:</p><pre>npm install -D typescript</pre><p>To use TypeScript in a monorepo, we will need TypeScript’s <a href="https://www.typescriptlang.org/docs/handbook/project-references.html">Project References</a>. Project references allow structuring TypeScript programs into smaller, interdependent projects, with improved build times, enforced logical boundaries, and incremental compilation.</p><h3>Root-level configuration</h3><p>To start, let’s create a root tsconfig.json file:</p><pre>{<br>  &quot;files&quot;: [],<br>  &quot;references&quot;: [{ &quot;path&quot;: &quot;packages/core&quot; }, { &quot;path&quot;: &quot;packages/cli&quot; }]<br>}</pre><p>We are using the references property to list all the projects of the monorepo. For each of the projects, we need to provide a path property with a relative file system path to the project root. The files field should contain an empty list to prevent double compilation of files (according to official TypeScript <a href="https://www.typescriptlang.org/docs/handbook/project-references.html#guidance">guidelines</a>).</p><p>Next, let’s create a base typescript config with compiler options, which all projects will inherit from. It needs to be a separate file and not part of the root tsconfig.json since all the projects of the monorepo will inherit from this configuration and extending the root tsconfig.json would create a circular dependency.</p><pre>{<br>  &quot;compilerOptions&quot;: {<br>    &quot;target&quot;: &quot;es2020&quot;,<br>    &quot;module&quot;: &quot;commonjs&quot;,<br>    &quot;sourceMap&quot;: true,<br>    &quot;strict&quot;: true,<br>    &quot;moduleResolution&quot;: &quot;node&quot;,<br>    &quot;esModuleInterop&quot;: true,<br>    &quot;forceConsistentCasingInFileNames&quot;: true,<br><br>    // project references<br>    &quot;composite&quot;: true,<br>    &quot;declaration&quot;: true,<br>    &quot;declarationMap&quot;: true,<br>    &quot;incremental&quot;: true,<br>    &quot;skipLibCheck&quot;: true,<br>    &quot;noEmitOnError&quot;: true<br>  }<br>}</pre><p>The above configuration, in addition to the common compiler options, contains some settings which need to be configured for project references to work correctly:</p><ul><li>the composite setting enables the project references and allows typescript to quickly find outputs of the referenced projects</li><li>declaration will cause .d.ts (compiled declarations) files to be generated for every TypeScript or JavaScript file, which project references depend on for external projects</li><li>enabling declarationMap allows to use editor features, such as “go to” across the project boundaries</li><li>incremental - enables incremental compilation</li><li>skipLibCheck - prevents the need to load and analyse all declarations upfront, improving performance</li><li>noEmitOnError - ensures that no output files (.js or .d.ts) are generated if the type checker detects errors.</li></ul><h3>Project-level configuration</h3><p>Now, we can create project-level tsconfig for <em>core</em> and <em>cli</em>, which will inherit from the base configuration:</p><pre>{<br>  &quot;extends&quot;: &quot;../../tsconfig.base.json&quot;,<br>  &quot;compilerOptions&quot;: {<br>    &quot;outDir&quot;: &quot;./dist&quot;,<br>    &quot;rootDir&quot;: &quot;./src&quot;<br>  },<br>  &quot;references&quot;: [{ &quot;path&quot;: &quot;../core&quot; }]<br>}</pre><p>Expect from the common compiler options inherited from the base config, we are also adding the outDir and rootDir here. This tells typescript where to place the compiled code and where to take the source code from. We also need to include the references field with paths to all the projects the project depends on. In the case of the <em>cli</em> package, we need to provide the path to the <em>core</em> package.</p><p>Let’s also create tsconfig for the <em>core</em> project. Since it doesn’t depend on any of the projects, we can omit the references field here:</p><pre>{<br>  &quot;extends&quot;: &quot;../../tsconfig.base.json&quot;,<br>  &quot;compilerOptions&quot;: {<br>    &quot;outDir&quot;: &quot;./dist&quot;,<br>    &quot;rootDir&quot;: &quot;./src&quot;<br>  }<br>}</pre><h3>Adding things to .gitignore</h3><p>Project references and TypeScript generate some files which we don’t want to include in the version control, therefore let’s update .gitignore with the following paths:</p><pre>*.tsbuildinfo<br>**/dist<br>...</pre><h3>.js → .ts</h3><p>For all project files (except <em>monthy-python</em>), let’s rename files from .js to .ts, replace require with import , and move the source files into src folder in each project:</p><pre>// packages/{core|cli}/index.js<br><br>require(&quot;core&quot;);<br>console.log(&quot;CLI package&quot;);</pre><h4>⬇️</h4><pre>// packages/{core|cli}/src/index.ts<br><br>import &quot;@spectacular/core&quot;;<br>console.log(&quot;CLI package&quot;);</pre><p>We also need to update the <em>monthy-python</em>’s index.js file, to require the compiled, javascript version of the <em>cli</em> index file (we cannot import typescript file into a javascript one):</p><pre>require(&quot;@spectacular/cli/dist/index.js&quot;);<br>console.log(&quot;Monthy Python&quot;);</pre><h3>Compiling and running</h3><p>To build the monorepo consisting of multiple typescript projects, we can use --build (-b for short) flag of tsc , which will run the smart incremental build process:</p><pre>npx tsc --build</pre><p>This does several things:</p><ul><li>finds all referenced projects</li><li>checks if projects are up-to-date</li><li>re-builds outdated projects in the correct order.</li></ul><p>Now, we can run the compiled files to see if everything still works as expected:</p><pre>$ node packages/core/dist/index.js<br>Core package</pre><pre>$ node packages/cli/dist/index.js<br>Core package<br>CLI package</pre><pre>$ node packages/monthy-python/index.js<br>Core package<br>CLI package<br>Monthy Python</pre><h3>We’ve done it! 🎉</h3><p>So that’s it, we’ve set up a monorepo using npm workspaces with support for TypeScript! If you want, you can see the full source code of the final setup on <a href="https://github.com/cecyliaborek/spectacular/tree/part-1-monorepo-ts">github</a>.</p><p>Stay tuned for the next parts of the series where we will be using this setup to create a testing framework!</p><p>If you want to learn more about monorepos, npm workspace or TypeScript project references, here are links to some resources I found useful:</p><ul><li><a href="http://monorepo.tools/">Monorepo.tools explanation of monorepos, their benefits and features, and designated tools</a></li><li><a href="https://docs.npmjs.com/cli/v7/using-npm/workspaces">npm workspaces documentation</a></li><li><a href="https://www.typescriptlang.org/docs/handbook/project-references.html">TypeScript project references</a></li><li><a href="https://moonrepo.dev/docs/guides/javascript/typescript-project-refs">Moonrepo’s guide for using TypeScript in a monorepo</a></li><li><a href="https://daveiscoding.hashnode.dev/nodejs-typescript-monorepo-via-npm-workspaces">Dave Is Coding blogpost “Node.js TypeScript monorepo via NPM workspaces”</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=307841e0ba4a" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>