Letterpad is an open-source and a high performant publishing engine for blogs built with react & graphql and runs ridiculously fast 🚀
Clone or download
Failed to load latest commit information.
.circleci fix: initialization (#66) Jul 8, 2018
.github refactored server.js Jun 8, 2018
__tests__ Prepare for cli lib (#100) Nov 13, 2018
admin Prepare for cli lib (#100) Nov 13, 2018
api Prepare for cli lib (#100) Nov 13, 2018
client [format] - trailing comma and indentation Oct 29, 2018
config Prepare for cli lib (#100) Nov 13, 2018
data Slate editor and plugins (#73) Jul 16, 2018
public Save css from admin panel (#96) Oct 27, 2018
shared [format] - trailing comma and indentation Oct 29, 2018
utils Prepare for cli lib (#100) Nov 13, 2018
webpack [format] - trailing comma and indentation Oct 29, 2018
.babelrc Upgraded babel to 7 (#94) Oct 25, 2018
.eslintignore [WIP] Fix eslint with webpack (#55) Jun 28, 2018
.eslintrc.js [format] - trailing comma and indentation Oct 29, 2018
.gitignore [fix] - move pm2 config in forever.sh and add it in .gitignore Nov 4, 2018
.prettierrc [format] - trailing comma and indentation Oct 29, 2018
.sequelizerc fix: initialization (#66) Jul 8, 2018
CODE_OF_CONDUCT.md Made admin refactoring Jun 11, 2018
CONTRIBUTING.md docs: add a friendly contribution intro (#67) Jul 8, 2018
LICENSE Initial commit Feb 13, 2017
README.md Prepare for cli lib (#100) Nov 13, 2018
package.json Prepare for cli lib (#100) Nov 13, 2018
postcss.config.js [format] - trailing comma and indentation Oct 29, 2018
sample.env Prepare for cli lib (#100) Nov 13, 2018
server.js [format] - trailing comma and indentation Oct 29, 2018
start.js well commented Jun 14, 2018
yarn.lock Prepare for cli lib (#100) Nov 13, 2018


Letterpad · Backers on Open Collective Sponsors on Open Collective GitHub license CircleCI Status

Letterpad is an open-source and a high performant publishing engine for blogs with a state-of-the-art technology. It uses React, Graphql, Express and Sequelize ORM. It is getting closer to releasing v1.0. Few of the core features are listed below:

  • Server side rendering
  • Multi author support
  • Comments (Disqus integration)
  • Google Analytics
  • Theme support
  • Multi-level navigation
  • Image optimizer
  • React with styled-components for styling
  • GraphQL for json API
  • Roles - Admin, Reviewer, Author, Reader
  • Markdown and RichText editor
  • Search Engine Optimised
  • Multi-language support with react-i18next (currently en, fr and pl)


To check letterpad in action, check out this Demo Site. You can visit the Admin Panel and login with

Email: demo@demo.com
Password: demo

A verbose documentation can be found at https://letterpad.app/docs.

Letterpad is an open source project, licensed under MIT. It runs ridiculously fast.

The API of letterpad exchanges information in json and you have full control over what data to get, set and display. You can build entire publishing apps on top of it, and completely customise the reader experience.


There are three steps to install letterpad in the development environment.

  1. Open a terminal and clone the project:
git clone https://github.com/letterpad/letterpad.git
cd letterpad
  1. Make a copy of sample.env and name it .env. Open it and change SECRET_KEY to a random string to secure your app. Then add your SMTP credentials so email can be sent. Change the database options accordingly. By default, letterpad uses sqlite.

  2. Install dependencies and run (use yarn to install dependencies):

NODE_ENV=dev yarn install
# Seed the database and run migrations
yarn dev

Now visit http://localhost:4040 and checkout the welcome page.

To visit the admin panel, visit http://localhost:4040/admin and login with

Email: demo@demo.com
PAssword: demo

Creating a build for production

The below command will create a build for the api, the admin dashboard and the theme. You will have to specify which theme you want to build.

theme=hugo yarn build
  • This will create a folder called apiBuild which will contain all contents of the api folder in ES5.
  • All the admin dashboard specific bundle will be in admin/public/dist folder.
  • All the theme specific bundles will be in client/hugo/public/dist folder.
  • The vendor bundles are common between admin and client. So they will be in public/js folder.

How it works ?

Letterpad needs two servers to run your blog. One server runs Graphql API and the other server runs the Letterpad Engine. However with little modification, you can combine this to use one server.

Themes have their own separate repository. While doing yarn install, the default theme hugo is fetched as a dependency during the installation. If the theme already exist, this step will be ignored.

Every theme should contain the below config file. This will have some metadata about your theme.

    "name": "Hugo",
    "short_name: "hugo",
        "A theme for writing classic blogs. Seo optimised, spa, disqus integrtion",
    "author": "Redsnow",
    "thumbnail": "/images/thumbnail.png"

This thumbnail path should exist inside the public folder of your theme

Read more about how to create a theme in the documention site.

Admin Authentication

Apollo Client is responsible to exchange data with graphql. After the users logs in to admin panel, a new token is created with the below information:

    email: "EMAIL",
    id: "USER_ID",
    role: "ROLE_NAME",
    permissions: ["PERMISSIONS"],
    name: "AUTHOR_FNAME",
    expiresIn: "30d" // "1d";
SECRET, // from .env file
{ expiresIn }

This token is then saved in localStorage. For every secured route in admin panel, a new token is issued and the previous token in localStorage is updated.

You can check the code of this here: shared/apolloClient.js. And you can check the code at the route level here - admin/containers/Secured.js

Graphql API

The graphql api code (ES6) for development is in the api folder. After the build, the folder apiBuild is created which contains all api code in ES5. This is used in production.

The api folder has well defined schemas in the schema folder and its resolvers in the resolvers folder. If you wish to make any change in the database label, then you should create a migration file. To create a migration file, enter this command:

yarn sequelize migration:generate --name specify-a-name-for-this-migration

yarn sequelize migration:generate --name addGoogleAnalyticsField

The above migration will be created in `api/housekeeper/migrations/xxxxxxxx-addGoogleAnalyticsField.js

In order to run the migrations, enter the below command.

yarn sequelize db:migrate

You can play around with the Graphql API locally on http://localhost:3030/graphql


Letterpad uses react-18next library to handle translations. To add, edit or delete trannslation objects, you can use the below commands:

usage: yarn [operation] [options] [key=value || key]
    operation (Required):
        -a, --add     Add key value pair to all files
        -s, --set     Set value of an existing key in all files
        -d, --del     Delete key from all files
            --sync    Sync all files with en.json
    options (Optional)
        -en     Operation only on this file
        -fr     Operation only on this file
        -pl     Operation only on this file
# Adds the translated value, only in en.json and for others leave it blank.
yarn translate --add save="Save"

# Set the translated value only in en.json and for others, set the value to empty string.
yarn translate --set oldKey="New Value"

# sets a translation object in one file
yarn translate --set -en oldKey="New Value"

# deletes a translation object from all files
yarn translate --del save

# deletes a translation object from one file
yarn translate --del -en tags.title

# sync all files with en.json
yarn translate --sync

VSCode setup

Extensions: Prettier, postcss-syntax, GraphQL, ESLint, DotENV, Babel ES6/ES7

npm i -g babel-eslint

For Prettier, it is recommended to add to the editor's settings.json to run on save.

"editor.formatOnSave": true


If you want to seed the database with sample data, run the below command:

// you should have babel-cli installed. Its good to have this package installed globally.
yarn seed

Addition Links:


Letterpad is in its early stages and requires support to move ahead. You can contribute through various ways like testing, ideas, recommendations, fixing bugs, documentation, logo design, assets, etc. You can join the slack channel (letterpad.slack.com) for discussions. Thanks.


This project exists thanks to all the people who contribute. [Contribute].


Thank you to all our backers! 🙏 [Become a backer]


Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]


Letterpad is released under the MIT License.