Skip to content

Commit

Permalink
Updated README (#1395)
Browse files Browse the repository at this point in the history 
closes https://linear.app/ghost/issue/ENG-1521

- updated development instructions
- updated deployment instructions
- general cleanup/rewording where judged useful
  • Loading branch information
@sagzy
sagzy authored Nov 13, 2024
1 parent 8c9fb13 commit a1cc096
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 43 deletions.
31 changes: 25 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Koenig

Ghost editor, based on the Lexical framework.

## Get started

This is a mono repository, managed with [lerna](https://lerna.js.org/).

To get started in this repo:
Expand All @@ -14,21 +18,36 @@ To add a new package to the repo:
- install [Slimer](https://github.com/TryGhost/slimer)
- run `slimer new <package name>`

## Run

- `yarn dev`
## Development

`yarn dev` runs the `koenig-lexical` package in development mode. Please refer to its [README](packages/koenig-lexical/README.md) for more information.

## Test

- `yarn lint` run just eslint
- `yarn test` run lint and tests

## Publish
## Deployment

Ghost core team only.

### Prerequisites

Create an `.env` file in `packages/koenig-lexical`, with environment variables for Sentry, so that we can track errors in the editor. There is a copy of this file in [1password](https://start.1password.com/open/i?a=FTXJSFO4TFAIVNFNGLK6UWNFTQ&v=2zqurhc5fmj5thjoob4oxwfllq&i=gcx3n7g2y5dibdn6n4zsgtm64y&h=ghost.1password.com).

```
VITE_SENTRY_ORG=""
VITE_SENTRY_PROJECT=""
VITE_SENTRY_AUTH_TOKEN=""
```

- `yarn ship` is an alias for `lerna publish`
- Publishes all packages which have changed
- Also updates any packages which depend on changed packages
### Deploy a new version

1. run `yarn ship` in the top-level Koenig directory to publish to npm
2. bump the Koenig dependencies in Ghost. Either:
- wait for Renovate to create a bump PR ([example](https://github.com/TryGhost/Ghost/pull/21606)) and merge it (recommended option)
- or, do it manually, by adding the new Koenig package versions to the `package.json` files in `Ghost/core` and `Ghost/admin`

# Copyright & License

Expand Down
75 changes: 38 additions & 37 deletions packages/koenig-lexical/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,34 @@
# Koenig - Lexical edition

Early stage re-write of Ghost's editor, using Lexical as the editor framework in place of mobiledoc-kit.
Ghost editor, based on the Lexical framework.

## Development

### Running the development version
The editor can be run in two modes:
- standalone mode: demo version that runs without a dependency on Ghost
- integrated mode: integrated into Ghost Admin

Run `yarn dev` to start the development server to test/develop the editor standalone. This will generate a demo site from the `index.html` file which renders the demo app in `demo/demo.jsx` and makes it available on http://localhost:5173
### Standalone mode

### Cards additional setup
Run `yarn dev` to start the editor in standalone mode for development on http://localhost:5173. This command generates a demo site from the `index.html` file, which renders the demo app in `demo/demo.jsx`.

### Integrated mode

In order to run the editor inside Ghost Admin, follow the 3 steps below:

1. Link Koenig server-side dependencies inside Ghost
- Run `yarn link` inside `Koenig/packages/kg-default-nodes` and `Koenig/packages/kg-lexical-html-renderer`
- Paste the output at the root of the Ghost monorepo:
- `yarn link @tryghost/kg-default-nodes`
- `yarn link @tryghost/kg-lexical-html-renderer`

2. Start Ghost in dev mode: inside the Ghost monorepo, run `yarn dev --lexical`.

3. Start the editor in dev mode: inside the Koenig monorepo, run `yarn dev`.

Now, if you navigate to Ghost Admin at http://localhost:2368/ghost and open a post, it will use your local version of the editor. Changes to the editor will be reflected inside Ghost Admin after a few seconds - the time for the editor to get rebuilt.

### Specific card setup

#### Gif card

Expand All @@ -23,19 +43,7 @@ How to get the tenor key is described here https://ghost.org/docs/config/#tenor

These cards make external web requests. Since the demo doesn't have a server to process these requests, we must fetch these resources on the front end. To do this we need to enable CORS, which is most easily done with a browser extension like 'Test CORS' for Chrome. Otherwise you will see blocked requests logging errors in the console. This can also be avoided by using test data directly without fetching via `fetchEmbed.js`.

### Running inside Admin

```bash
# Within koenig-lexical, start all the build/preview steps
yarn dev

# Within Ghost, run `yarn dev` with `--lexical`
yarn dev --lexical
```

Admin should now load your local version of Lexical.

Note: if you need to run your local packages of `kg-default-nodes` and `kg-lexical-html-renderer`, you will need to run `yarn link` in those repositories and run the output in `ghost/core`. Otherwise `ghost/core` will be using the latest published version listed in `package.json`.
## Additional notes

### Project structure

Expand All @@ -47,7 +55,7 @@ The main module source. `/src/index.js` is the entry point for the exposed modul

Used for developing/demoing the editor. Renders a blank editor with all features enabled.

### Set up details
### Styling

**CSS**

Expand Down Expand Up @@ -100,30 +108,23 @@ Node enables ECMAScript modules if `type: 'module'` in package.json file. It lea
- [No require.extensions](https://github.com/GrosSacASac/node/blob/master/doc/api/esm.md#no-requireextensions). It means we don't have control over the extensions list. Further will be a description of why this is important.

We can make file extension optional with [--experimental-specifier-resolution](https://nodejs.org/api/cli.html#--experimental-specifier-resolutionmode)
flag, which we use. But node is not recognized `jsx` extension.
It can be solved with [node loaders](https://github.com/nodejs/loaders-test/tree/main/commonjs-extension-resolution-loader), whereas
as they're still in [experimental mode](https://nodejs.org/api/esm.html#esm_experimental_loaders), there is no appropriate
flag, which we use. But node is not recognized `jsx` extension.
It can be solved with [node loaders](https://github.com/nodejs/loaders-test/tree/main/commonjs-extension-resolution-loader), whereas
as they're still in [experimental mode](https://nodejs.org/api/esm.html#esm_experimental_loaders), there is no appropriate
implementation for this use case.
The same issue was raised in the babel repo, but the loader won't be added while node loaders are
in [experimental mode](https://github.com/babel/babel/issues/11934).
The same issue was raised in the babel repo, but the loader won't be added while node loaders are
in [experimental mode](https://github.com/babel/babel/issues/11934).

We can add our loader implementation to solve the issue. Still, in reality, we shouldn't need real
JSX components in e2e tests. It can be a situation when some constants locate in the `jsx` file. In this case,
we can move them to js file. If it is a problem in the future, we can add our implementation of the loader or
We can add our loader implementation to solve the issue. Still, in reality, we shouldn't need real
JSX components in e2e tests. It can be a situation when some constants locate in the `jsx` file. In this case,
we can move them to js file. If it is a problem in the future, we can add our implementation of the loader or
add an extension to all imports in the project.

## Deployment

To deploy the changes made in Koenig Lexical and integrate them into Ghost, follow these steps:

1. Run `yarn ship` in the top-level Koenig monorepo. This command will update the editor used on Ghost by fetching the latest version from jsdelivr.

2. Bump the version of `@tryghost/kg-default-nodes` in the Ghost repository. This step is necessary for rendering to work correctly with newly added or updated nodes. Failure to perform this step may result in issues when saving posts on Ghost that use the new cards.

3. Run `/main` in Slack and wait for the new version to build to test on staging.

### Editor integration

There's a [vitest vscode extension](https://marketplace.visualstudio.com/items?itemName=ZixuanChen.vitest-explorer) that
There's a [vitest vscode extension](https://marketplace.visualstudio.com/items?itemName=ZixuanChen.vitest-explorer) that
lets you run and debug individual unit tests/groups directly inside vscode.

## Deployment

Koenig packages are shipped via Lerna at the monorepo level. Please refer to the monorepo's [README](../../README.md) for deployment instructions.

0 comments on commit a1cc096

Please sign in to comment.