DEV Community: Kazane Shimizu

Can I create another WordPress that satisfies humanity?

Kazane Shimizu — Mon, 27 Nov 2023 17:45:00 +0000

With a strong presence in the industry, WordPress is employed by 40% of all websites. Even two decades since its inception, it continues to be the preferred platform for crafting blogs and websites. However, viewed from an engineer's perspective, the system poses numerous challenges.

I'm currently offering an open-source Headless CMS named Collections, a project I've been passionately developing over the past year. My motivation stems from a commitment to redefine the CMS landscape, addressing the issues I encountered with WordPress. Below is a summary of the development journey over the past year.

The Darkness of Black Magic

WordPress is a meticulously designed system, offering the convenience of updating the software from the admin panel to ensure users always have access to the latest version. It boasts extensive customization options and can be further enhanced through external plugins.

Yet, contamination from haphazardly added plugins and what some refer to as Black Magic code has hindered updates and exposed the system to vulnerabilities.

Indeed, the responsibility for this issue lies squarely with certain users.

Nevertheless, it's possible that this wasn't driven by malicious intent but rather a pursuit of a more advanced specification. In this context, extending beyond a user-specific problem, it suggests that humanity might no longer find satisfaction in the default WordPress.

Possibilities felt for headless

Headless is an architecture that separates the front end from the back end.

Traditional CMSs integrate both the front end and back end. By separating them, the front end can be tailored to diverse user segments, offering simplicity for light users and high customizability for advanced users. This system's separation naturally enhances maintainability.

Although adopting a headless approach may initially appear to exclude light users, we are confident that, in the long run, it's a system capable of satisfying a broad range of users.

Headless is beginning in other industries

The headless trend is already underway in other industries.

Tiptap, a tool that's becoming more prevalent in technical articles, serves as a specialized backend editor. Naturally, it doesn't operate as a standalone editor.

Leecason / element-tiptap

🌸A modern WYSIWYG rich-text editor using tiptap and Element UI for Vue3 (1.0 for Vue2)

Element Tiptap Editor

A WYSIWYG rich-text editor using tiptap2 and Element Plus for Vue3

that's easy to use, friendly to developers, fully extensible and clean in design.

🧊 Legacy

Element Tiptap 1.0

📔 Languages

English | 简体中文

🎄 Demo

👉https://leecason.github.io/element-tiptap

👾Code Sandbox

✨ Features

🎨Use element-plus components
💅Many out of box extensions (welcome to submit an issue for feature request👏)
🔖Markdown support
📘TypeScript support
🌐I18n support(en, zh, pl, ru, de, ko, es, zh_tw, fr, pt_br, nl, he). welcome to contribute more languages
🎈Events you might use: create, transaction, focus, blur, destroy
🍀Fully extensible, you can customize editor extension and its menu button view
💻Also can control the behavior of the editor directly, customize the editor for yourself.

📦 Installation

NPM

yarn add element-tiptap

npm install --save element-tiptap

Install plugin

import

…

View on GitHub

By integrating it with the front end or developing a custom editor, Tiptap becomes adaptable to various user groups.

Users find the flexibility to switch the UI based on their proficiency level appealing. For Tiptap, separating the front end, with its numerous issues and requests, enables a concentrated focus on back-end feature development.

In the end, integrated software tends to diverge from the preferences of power users. Therefore, adopting a headless approach becomes an inevitable trend.

Collections was born!

Taking these considerations into account, I personally created an open-source headless CMS called Collections!

Index – Collections

A headless CMS that transforms your WordPress into an API. No need to copy and paste old posts anymore.

collections.dev

Here is a brief introduction to the features.

Define the data model

Fields can be added, ranging from text and markdown to images, etc., and the data model is established. Upon completion of the registration, the database schema is dynamically generated.

Register your content

Next, register content according to the data model.

Call as API

The endpoint is now set up!🥳
You can retrieve the registered content by making an API call from the front end or a smartphone app.

Support for migration from WordPress

Easily import your exported article data from WordPress by simply dragging and dropping. Say goodbye to the tedious task of copying and pasting old articles to get started!

Three Commitments

Must be open source

Effective collaboration with the front end is crucial for a headless CMS. Consequently, having open code becomes essential as a shared language for comprehending the interface and exchanging feature requests.

In contrast to Tiptap, transitioning to a headless CMS incurs a relatively high cost. This is due to the fact that, unlike editors which are easily replaceable tools, CMSs entail the complexity of data migration.

Moreover, the absence of normalized data in WordPress poses a migration challenge. To address this directly, Collections has crafted a migration tool as a plugin, which is also open source and available to the community.

https://github.com/collectionscms/plugin-wp-importer

Currently, we only have article data, but with the collaboration of developers worldwide, we aim to develop a tool that enables the transfer of all types of data!

Developer First

Collections is designed with a strong emphasis on developers. It can be deployed in any environment, offers ease of use, and comes with comprehensive documentation. A supportive developer community is also accessible on Discord.

In addition, the UI provides

😻 Markdown with GFM
🌒 Dark mode
📱 Responsive

We've got a complete set of essential tools for engineers to do their writing! 😎

Can be introduced with a one-liner

No matter how fantastic a product is, if it's challenging to implement, people won't use it. But, of course, there's no need to worry!

npx create-collections-app my-app

Installing the software is a breeze with just a few commands!

All that's left is to respond to the installer's questions to finalize the setup process.

// Select your database client
? Which one? SQLite is the simplest. (Use arrow keys)
❯ SQLite
  MySQL / MariaDB
  PostgreSQL

Collections Architecture

Backend UI

The backend UI is a combination of React + MUI + Ant Design.

For a headless CMS, all you need is an administration screen, so there's no requirement for an overly elaborate UI. That's why we opted for MUI due to its refined components. We chose Ant Design solely for its icons, as we personally appreciate its aesthetic.

API

The API is a powerful blend of Node.js + Express. When evaluating backend combinations, a crucial aspect is that it can be deployed in any environment. Hence, vendor-locked options like Next.js were excluded from the candidate list.

Database

Opting for RDB and supporting multiple vendors, we chose RDB for its versatility in deployment environments, ease of migration from WordPress, and the preference of many engineers who find RDB more user-friendly than NoSQL.

Given the dynamic nature of the schema, we employ Knex, a query builder, for database access.

Image

Currently, S3 is supported. Looking ahead, we plan to expand support to include Google and Azure storage, along with CDN delivery. There's quite a bit of work ahead... 😅

Hosting

As evident from the architecture, it comprises a fundamental structure. Consequently, it is adaptable to various environments, whether within or outside the network!

For your convenience, we've provided instructions for deploying on Lightsail, which is essential for cost-effective usage. Feel free to give it a try!

Amazon Lightsail – Collections

A headless CMS that transforms your WordPress into an API. No need to copy and paste old posts anymore.

collections.dev

Future Development

Launch of cloud version

In 2024, we're gearing up to introduce a cloud version. While it will come at a modest cost, it's perfect for those seeking swift implementation without the hassle of software updates. Stay tuned for its release, and we hope you're as excited about it as we are!

Build out migration tools from WordPress

Migrating 40% of our websites is a formidable undertaking, but we're collaborating with developers worldwide to tackle the challenge! We're counting on the support of developers from across the globe to help us overcome this hurdle!

Build an ecosystem with front-end

Observing examples like Tiptap and CMS, I anticipate a continued trend of increasing separation between the front and back end, leading to a more loosely coupled relationship between software components.

If you're a developer interested in creating applications in conjunction with Collections in the future, we'd love to collaborate with you! Let's work together to build a robust ecosystem 💪

Feedback and Request

Want to try Collections?

Collections is open source, available for free use by anyone. If you need help with implementation, feel free to join us on Discord 👇

https://discord.gg/a6FYDkV3Vk

Finally

A CMS is a product whose value is derived from its enduring appeal. The enduring popularity of WordPress, even after two decades, attests to this. I firmly believe that this is the very realm where engineers should leverage their strengths and dedicate their careers.

Resources
GitHub — Open source repository
Demo — Demo for those who want to get a taste of Collections functionality
Document — General Information, API Information
Discord — Developer Community
X — Latest Product Information

Your appreciation in the form of liking our articles or simply giving us a star on GitHub would be truly uplifting!

Thank you for your support!! 🙌

Over 10 Years of Indie Hacking, I can stay active at 40+

Kazane Shimizu — Mon, 06 Nov 2023 12:30:00 +0000

Hello, I turned 42 this year and I'm an active freelance engineer.

I continue to write code, thanks to the experience I've gained over more than a decade of indie hacking and my product contributions.

I've created about 10 products so far, and some have even received funding. However, solo product development remains challenging. When I first started, I often abandoned projects halfway through. But now, with my own set of rules in place, I consistently see projects through to completion.

In this edition, I've distilled these rules into 10 methods!

What are you developing?

I'm currently working on a headless CMS called 'Collections'.

Collections allows you to API your WordPress articles with a simple drag-and-drop feature. It's built entirely in TypeScript, runs on an RDBMS, and is open-source 💚.

While there are various headless CMS options available, Collections stands out by offering a seamless transition from WordPress.

Index – Collections

A headless CMS that transforms your WordPress into an API. No need to copy and paste old posts anymore.

collections.dev

Benefits of Indie Hacking

Numerous articles have extensively covered this topic, so I won't go into detail here. Just like strength training, consistency yields significant benefits over an extended period, gradually accumulating.

On the flip side, the downsides are...well, there really aren't many! If I were to mention one, it might be the time commitment. However, you could also view it as an investment in experience. As someone who has worked in a brokerage firm, it's challenging to find a more cost-effective investment than this 😆.

10 Methods

Let's get straight to it. Here are the top 10 essential factors for reaching the finish line

Recognize developers' strengths.
Clearly define the problems to be addressed.
Avoid setting daily quotas.
Establish development deadlines.
Research competitors and emulate their methods.
Find a reliable partner.
Be cautious with new tech.
Focus only on critical issues.
Don't expect a spectacular launch.
Make it public.

📌 1. Recognize developers' strengths

Even in an era where non-engineers can create products without coding, engineers have the advantage of sustaining product development long-term without incurring production costs.

Most services that people desire have already been developed by predecessors, making it nearly impossible to create a groundbreaking product from scratch.

Even well-funded companies always operate within budget constraints, leading to ongoing debates on whether to "pull the plug" or "invest more".

On the other hand, individuals can easily keep creating and improving their work, which is a significant advantage.

In my opinion, it's wiser to focus on developing products that can provide long-term value rather than blindly following industry trends.

📌 2. Clearly define the problems to be addressed

Once this is determined, the product becomes easier to create. For the most part

For yourself
For someone close to you
For someone you don't know who has a challenge

With the third option, the potential user base is larger, making it easier to scale the product. However, it also becomes more challenging to identify common issues. During your early journey as an indie hacker, it's advisable to create a product for yourself or someone in your close circle.

You've likely heard the advice to "share your product as soon as you create it and gather feedback" at least once. While this is the right approach, receiving unintended feedback expressing that they "don't need" or "won't use" the product can be disheartening, potentially demotivating you and causing you to drop out of the race.

Therefore, in the early stages, the main goal should be to find satisfaction in what you've created.

📌 3. Avoid setting daily quotas

One strategy I've experimented with, but found to be ineffective, involves setting personal quotas, like 'write code every day' or 'complete it this week.' To be honest, it's quite simple to come up with various excuses and rationalize why I didn't take certain actions. However, when these self-imposed goals aren't achieved, it is easy to lose motivation.

So, it is much more important to keep the motivation for 'making it' high. The key to completion is to enjoy the process of creation itself 😊.

📌 4. Establish development deadlines

In contrast to not setting quotas as mentioned earlier, consider setting deadlines for development. The most significant adversaries for indie hacking are 'boredom' and 'giving up'.

No matter how high your motivation is, one of these two outcomes is bound to occur. While it's a different story for services that require extensive effort to create, when you believe that you can create something great with time, it may not always be the case. As you start noticing flaws, the fear of continuously releasing, making fixes, or worst of all, starting over becomes overwhelming. As you tinker around, you might get bored and end up not releasing at all.

So, let's release products before these pressures build up.

The goal should be to release within six months, if it takes more than a year, it should be considered too late.

📌 5. Research competitors and emulate their methods

I believe you can appreciate the importance of maintaining motivation in indie hacking. However, on the flip side, what are the moments that most often diminish motivation?

One such moment is when you initially think your idea is unique and then discover a similar service already exists 😱.

The shock of this discovery can make you feel like all the efforts you've put in so far have been instantly wiped away! Unfortunately, this often stems from insufficient preliminary research...

When a new idea strikes, and you're eager to 'develop it right away,' it's a good idea to temper that excitement a bit and start by searching on GitHub for similar software. Just because you find something similar doesn't mean there's no value in creating something new. In fact, by addressing the shortcomings of existing competitors, you can create an attractive product.

Additionally, thoroughly emulate the common elements. By identifying 2 or 3 similar projects in terms of language and structure, you can streamline concerns during implementation and prerequisite knowledge.

And thoroughly emulate the common elements. By finding 2 or 3 similar things in terms of language and structure, you can shortcut the points of concern during implementation and the prerequisite knowledge.

📌 6. Find a reliable partner

When you're developing something on your own, you might start feeling like, "Do I need this service?" or become fearful of releasing it. That's why it's important to occasionally bounce your ideas off someone else.

During these times, it's great to consult with someone who has experienced success with a product, but even fellow indie hackers work well! On the contrary, it's better to avoid seeking advice from friends or acquaintances who might find it easy to say no. Users might know what's good, but they won't fully understand until they've experienced it. Consequently, they might just point out glaring issues or say, "I won't use it" without diving into the details.

Even if you don't have someone close by to consult with, indie hackers often share common traits and interests. So, reaching out to someone for advice is unlikely to lead to hard feelings.

📌 7. Be cautious with new tech

One common challenge faced by developers is this:

The better you are in a specific field, the stronger the temptation to introduce new technologies or tools becomes. However, this can increase the learning curve and slow your progress, unless these additions are truly essential for your project. It's best to steer clear of new technologies unless they are absolutely vital for the service you're creating. With many tasks on your plate, particularly as you approach the release, taking on non-essential technologies can complicate the process.

📌 8. Focus only on critical issues

This is the second common pitfall that developers often encounter.

In the world of indie hacking, you don't incur traditional costs. However, due to the nature of this profession, the desire to perfect specifications and resolve bugs can lead to unnecessary time consumption, resulting in endless delays when trying to release a product.

In conventional software development, we typically use tools like JIRA to manage issue statuses, with labels such as highest, high, medium, low, and lowest. In contrast, indie hacking simplifies this to just two choices: critical or non-critical.

Unless it's a critical feature or a critical bug, everything else should be added to the backlog.

📌 9. Don't expect a spectacular launch

It's tough to put in a year of work only to have no one pay attention. And the creeping burnout can be intense... 😱

Think of the launch as not the goal but merely the first milestone on a long roadmap. What's crucial is to keep improving it after the launch!

Some people might be concerned that if they release their ideas incrementally, they could be copied. However, groundbreaking ideas don't come by often. The strategies that result in user growth are the truly innovative ideas. So, don't worry and keep sharing your ideas openly and freely.

📌 10. Make it public

You don't need to keep it running indefinitely. Creating just one or two articles and leaving it at that is sufficient. It can serve as a record, and if you feel like you've reached a conclusion within yourself, it can also bring a sense of accomplishment.

The important thing is to put it out into the world in a usable form!

Finally

Indie Hacking is enjoyable! It's like the foundation of our thirst for knowledge.
Let's bring a new experience to someone else!

Happy Coding!!

Running Jest for multiple DB with GitHub Actions

Kazane Shimizu — Mon, 30 Oct 2023 12:45:00 +0000

Introduction

If you're working on an application that supports multiple databases, even minor adjustments can lead to issues related to SQL dialects or query builder specifications like Knex.

The headless CMS I'm currently developing also offers users the option to choose their preferred database, so it's essential to ensure not only the logic but also the ability to perform CRUD operations correctly in each database when developing features.

The same holds true for testing, which requires some clever strategies, such as connecting to multiple databases to verify a single scenario. However, by automating these processes through continuous integration (CI), you can reduce the likelihood of unexpected bugs.

In this article, we'll demonstrate how to use GitHub Actions to execute Jest tests on multiple databases while creating a disposable environment.

All the code is available on GitHub for your reference!

collectionscms / collections

Collections is a headless CMS for Answer Engine Optimization (AEO).

⭐ What is Collections

Collections is a headless CMS for Answer Engine Optimization (AEO).

Our mission is to deliver both human and AI friendly content as people are moving from Google it to Ask AI.

Try Live Demo View Blog Demo

Features

🪄 AI supports SEO
🌐 Multilingual content
🖊 Notion-like editor
🕘️ Article versioning

📚 Usage & Documentation

Extended documentation is available on our website.

🚀 Installation

How to start using Collections on localhost.

// clone
git clone git@github.com:collectionscms/collections.git
cd collections

// env
cp .env.sample .env
vi .env - make it your environment

// install direnv
brew install direnv
vi ~/.zshrc - add `eval "$(direnv hook zsh)"`
source ~/.zshrc
direnv allow .

// init
yarn install
yarn db:refresh
yarn dev

Add the following lines to the /etc/hosts

127.0.0.1   app.test.com
127.0.0.1   en.test.com
127.0.0.1   ja.test.com

Open http://app.test.com:4000/admin to view your…

View on GitHub

Environment

	Contents
Test tool	Jest
DB	MySQL, PostgreSQL, SQLite.... .etc. As many as you want!
CI	GitHub Actions

Goal

Don't repeat "MySQL is OK, PostgreSQL is an error 😱"

Test Flow

Launch Docker
Migration /seed in Jest setup
Test execution on multiple DBs!

Jest

Configuration

Begin by initializing the database for testing purposes. You can specify the setup code in the Jest configuration file's globalSetup section.

For the finer details, please consult the repository, as we've excluded all but the most essential code.

/** @type {import('ts-jest').JestConfigWithTsJest} */
export default {
  ...
  globalSetup: './test/setups/setup.ts',
  ...
};

https://github.com/superfastcms/superfast/blob/main/jest.integrations.config.mjs

In this stage, migrations are executed, and seed data is provided for each database to be tested. The key distinction is that these processes are repeated within an array known as testDatabases.

export default async (): Promise<void> => {
  for (const testDatabase of testDatabases) {
    const database = knex(config.knexConfig[testDatabase]!);

    if (testDatabase === 'sqlite3') {
      writeFileSync('test.db', '');
    }

    await database.migrate.latest();
    await database.seed.run();
  }
};

https://github.com/superfastcms/superfast/blob/main/test/setups/setup.ts

Next is the test code.

Test Codes

While iterating with testDatabases as well, you can write the usual test cases 🙆

describe('Users', () => {
  describe('Create', () => {
    it.each(testDatabases)('%s - should create', async (database) => {
      const connection = databases.get(database)!;

      const repository = new UsersRepository(tableName, { knex: connection });
      const result = await repository.create(user);

      expect(result).toBeTruthy();
    });
  });
});

An important point to remember is that afterAll discards all connections. Failing to do so can result in Jest continuing to run for several minutes without terminating the process, even after the test has passed.

const databases = new Map<string, Knex>();

beforeAll(async () => {
  for (const database of testDatabases) {
    databases.set(database, knex(config.knexConfig[database]!));
  }
});

afterAll(async () => {
  for (const [_, connection] of databases) {
    await connection.destroy();
  }
});

https://github.com/superfastcms/superfast/blob/main/test/api/repositories/users.test.ts

Test run

With the setup now complete, let's get started!

yarn test:int

The test succeeds like this~~Yay!! 🙌

yarn run v1.22.19
$ node --loader ts-node/esm --experimental-vm-modules node_modules/jest/bin/jest.js --config=jest.integrations.config.mjs
(node:2144) ExperimentalWarning: Custom ESM Loaders is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

Setup databases: [ 'sqlite3', 'mysql', 'maria', 'postgres' ]
🟢 Starting tests! 

(node:2144) ExperimentalWarning: VM Modules is an experimental feature and might change at any time
PASS test/api/repositories/projectSettings.test.ts (6.145 s)
PASS test/api/repositories/users.test.ts

-------------------------|---------|----------|---------|---------|------------------------------------------------------
File                     | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s                                    
-------------------------|---------|----------|---------|---------|------------------------------------------------------
All files                |   72.97 |    83.33 |      40 |   72.97 |                                                      
 src                     |     100 |      100 |     100 |     100 |                                                      
  env.ts                 |     100 |      100 |     100 |     100 |                                                      
 src/api/database        |   39.74 |      100 |       0 |   39.74 |                                                      
  connection.ts          |   39.74 |      100 |       0 |   39.74 | 32-78                                                
 src/api/repositories    |   54.77 |    82.35 |   41.66 |   54.77 |                                                      
  base.ts                |   87.91 |       70 |   54.54 |   87.91 | 31-35,77-78,85-86,89-90                              
  projectSettings.ts     |   72.22 |      100 |      50 |   72.22 | 13-17                                                
  users.ts               |   29.54 |      100 |   27.27 |   29.54 | 13-17,25-30,40-49,52-63,66-81,84-107,110-116,119-131 
 src/exceptions          |      68 |      100 |   33.33 |      68 |                                                      
  base.ts                |   66.66 |      100 |      50 |   66.66 | 12-17                                                
  invalidCredentials.ts  |   71.42 |      100 |       0 |   71.42 | 5-6                                                  
 src/exceptions/database |     100 |      100 |     100 |     100 |                                                      
  recordNotUnique.ts     |     100 |      100 |     100 |     100 |                                                                                                         
-------------------------|---------|----------|---------|---------|------------------------------------------------------

Test Suites: 2 passed, 2 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        8.422 s
Ran all test suites.

🏁 Tests complete!

In this scenario, we're conducting tests across all databases (SQLite, MySQL, MariaDB, and PostgreSQL). However, running these tests each time can be time-consuming and resource-intensive in a CI environment. In such cases, it's advisable to pass specific tests as parameters, as demonstrated below, to streamline the process.

export const allDatabases = ['sqlite3', 'mysql', 'maria', 'postgres'];
export const testDatabases = process.env.TEST_DB?.split(',').map((v) => v.trim()) ?? allDatabases;

In my headless CMS, I use only SQLite for all DBs except when I modify the logic.

TEST_DB=sqlite3 yarn test:int

GitHub Actions

Having successfully executed the tests locally, you can now set them up as a GitHub Actions workflow. Automating the testing process helps minimize the chances of unexpected issues arising from minor adjustments or library updates made through Renovate.

jobs:
  integration:
    name: ${{ matrix.database }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        database:
          - sqlite3
          - mysql
          - maria
          - postgres
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Yarn install
        run: yarn install

      - name: Start Services
        if: matrix.database != 'sqlite3'
        run: docker compose -f test/docker-compose.yml up ${{ matrix.database }} -d --quiet-pull --wait

      - name: Run Tests
        run: TEST_DB=${{ matrix.database }} yarn test:int

https://github.com/superfastcms/superfast/blob/main/.github/workflows/integration-full.yml

In continuous integration (CI), the focus is on the database to be tested for each pull request. While there are various approaches, one method involves specifying paths to run any files that have been modified by a PR, especially if they relate to backend code or the test code itself.

pull_request:
  branches:
    - main
  paths:
    - src/api/**
    - test/api/**
    - package.json
    - .github/workflows/integration-full.yml

Alternatively, you can save time and CI resources by exclusively using SQLite, as it doesn't necessitate Docker startup!

Finally

We are developing a headless CMS Collections that will turn WordPress articles into an API with drag and drop 🚀

Index – Collections

A headless CMS that transforms your WordPress into an API. No need to copy and paste old posts anymore.

collections.dev

Full TypeScript, works with RDB. And it is open source. Please try the Live Demo.

Happy Coding!!

Next.js + Redoc to create a low-latency API references

Kazane Shimizu — Sat, 28 Oct 2023 05:56:19 +0000

I'm currently developing an open-source headless CMS called Collections. During this project, the need arose for a public API specification, and we decided to try out the combination of Next.js (Nextra) and Redoc, which turned out to be quite effective. We've documented the procedure for your reference.

API specifications, like those using OpenAPI (Swagger), are typically created for each project, but sharing them with the public may not happen very often. Nonetheless, this is a domain where technology trends evolve relatively slowly, so it's worth keeping in mind!

Completed product

The published page is here

All code is available on GitHub for your reference.
https://github.com/collectionscms/collections/blob/main/docs/pages/reference/api.en.mdx

What is Redoc?

This tool takes YAML files defined in the OpenAPI specification and transforms them into static documents in HTML format. It's an open-source tool.

In the case of Collections, we employ Nextra, a Next.js-based static site generator, to produce the complete document, which is subsequently integrated and rendered.

Install Redoc as a component of React

Let's get started and follow the official steps. First, install @redocly/cli and its associated dependencies.

npm i react react-dom mobx styled-components core-js

Prepare yaml file

Next, create a yaml file based on the OpenAPI specification.
The Collections API specification is attached for your reference.

https://github.com/collectionscms/collections/blob/main/docs/data/api.yaml

If you are using VSCode, you should install the OpenAPI (Swagger) Editor, which will warn you of syntax errors so that you can proceed with your work quickly.

https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi

Add to component

When the file is ready, fill the page with Redoc components and it will automatically generate and output HTML!

import { RedocStandalone } from 'redoc';

<RedocStandalone specUrl="url/to/your/spec"/>

However, it is not possible to reference local files in the specUrl. This has been exchanged on GitHub issues, but is due to the same-origin policy and security reasons.
https://github.com/Redocly/redoc/issues/149#issuecomment-359285569

One option is to save yaml to S3, but this is more work, and I don't want to add a CI job to upload the files.

Distribute via Next.js API and convert to SSG

Therefore, we solved this problem by using the Next.js API to respond to yaml and passing it on.

export default function handler(_req: NextApiRequest, res: NextApiResponse<ResponseData>) {
  const fullPath = path.join(dataDirectory, 'api.yaml');
  const fileContents = fs.readFileSync(fullPath, 'utf8');
  res.status(200).json(YAML.parse(fileContents));
}

Well, this would have been fine, but the rendering is quite slow due to each request, so we need to do something more. Redoc also has a property called spec that passes an object instead of a URL.

export const getStaticProps = ({ params }) => {
  return fetch(`https://collections.dev/api/openapi`)
    .then((res) => res.json())
    .then((repo) => ({
      props: {
        ssg: repo,
      },
    }));
};

export const Redoc = () => {
  const data = useData();
  return <RedocStandalone spec={data} />;
};

By pre-rendering and passing the object in SSG in this way, the response surface was successfully cleared!

Performance

$ curl 'https://collections.dev/reference/api/' -H 'Accept-Encoding: gzip, deflate, sdch' -H 'Accept-Language: en-US,en;q=0.8,ja;q=0.6' -H 'Upgrade-Insecure-Requests: 1' -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.86 Safari/537.36' -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8' -H 'Connection: keep-alive' --compressed -o /dev/null -w  "%{time_starttransfer}\n" -s

0.239587
0.249859
0.255718
0.249946
0.253883

The response time is usually within 300 ms.

First Contentful Paint is also 0.6sec. I think we can give it a passing grade since it is not a page that requires any further improvement or SEO.

Finally

I'm building an open source headless CMS Collections that turns WordPress into an API 🚀

It has Markdown (with GFM), dark mode, and other features that make it comfortable to write with. We also have a Live Demo, so please feel free to try it 🙌🙌

See you soon!