Getting Started
\n\n## Getting Started\n\nThe following steps walk you through the development of a **Hello World** plugin that adds a simple message to the annotation editor.\n\n### Prerequisites\n\nBefore starting, make sure you have the following installed:\n\n- NodeJS (version 20 recommended)\n- npm\n\n## Create Your Project\n\nThere is a GitHub template that you can use to quickly bootstrap your new project. However if you prefer you can build your project from scratch.\n\n\n
\n\nCreate Project with GitHub Template
\n\n### Step 1: Create New Project From Template\n\n1. In your browser, go to the [template repository](https://github.com/recogito/plugin-template)\n2. Above the file list, click Use this template.\n3. Select Create a new repository.\n\n\n\n4. Use the Owner dropdown menu to select the account you want to own the repository.\n5. Type a name for your repository, and an optional description.\n\n\n\n6. Choose a repository visibility.\n\n7. Click `Create repository`.\n\n### Step 2: Clone Repository to Your Local Workspace\n\nIn a terminal window clone the repository that you just created:\n\n```sh\ngit clone https://github.com/[Your Repository].git\n```\n\nChange your directory to the cloned repository and run:\n\n```sh\nnpm install\n```\n\nOpen your `package.json` file and name your plugin. It should match the name you created above (i.e. @performant/plugin-hello-world).\n\n```diff\n{\n- \"name\": \"@recogito/plugin-template\",\n+ \"name\": \"@performant/plugin-hello-world\"\n \"version\": \"0.1.0\",\n- \"description\": \"A template to boot-strap a new Recogito Studio plugin project.\",\n+ \"description\": \"My new Recogito Studio Plugin\"\n ...\n}\n```\n\nYou can now proceed to [Step 3](#step-3-create-the-plugin-entry-point). You will find that some of the proceeding steps have been taken care of by the template.\n\n\n
\n\n**Once you have completed with the [Template](#step-1-create-new-project-from-template) or [Manual](#step-1-initialize-a-new-plugin-project) Project Creation instructions, proceed:**\n\n### Step 3: Create the Plugin Entry Point\n\nCreate a subdirectory `src` in your project root. Inside the `src` directory, create a file called `index.ts`. This file is your main plugin entry point that will get registered by Recogito Studio. It **must provide a default export**, which must be an Astro Integration, and must register a single **Plugin**.\n\n```ts\nimport type { AstroIntegration } from \"astro\";\nimport { Plugin, registerPlugin } from \"@recogito/studio-sdk\";\n\nconst HelloWorldPlugin: Plugin = {\n name: \"My Hello World Plugin\",\n\n module_name: '@performant/plugin-hello-world',\n\n description: \"An example Hello World plugin.\",\n\n author: \"Performant Software\",\n\n homepage: \"https://www.performantsoftware.com/\",\n};\n\nconst plugin = (): AstroIntegration => ({\n name: \"plugin-hello-world\",\n hooks: {\n \"astro:config:setup\": ({ config, logger }) => {\n registerPlugin(HelloWorldPlugin, config, logger);\n },\n },\n});\n\nexport default plugin;\n```\n\nYour plugin package must expose this default as the root module. Include the following in your `package.json`:\n\n```jsonc\n{\n // ...\n \"exports\": {\n // Main module entry point – the default Astro Integration export\n \".\": \"./dist/index.js\"\n }\n}\n```\n\n### Step 4: Install the Test Application Template\n\nAt this point, you have a technically valid Recogito Plugin. It doesn't actually do anything yet. But it will correctly register itself with Recogito Studio when you start it.\n\nTherefore, this is a good time to set up the **test application** included with the SDK. The test application provides a convenient development environment you can use to:\n\n- test if your plugin gets correctly registered as an Astro Integration.\n- preview the UI extensions they provide (none yet – but we'll get to that).\n\nTo set up the test application template, run:\n\n```sh\nnpx copy-template\n```\n\nThis will copy the test application to a `.dev` folder in your project. We recommend adding the following line to your project's `package.json`, so you can conveniently start the test application using `npm run dev`:\n\n```jsonc\n{\n // ...\n \"scripts\": {\n \"dev\": \"npm start --prefix .dev/\"\n //...\n }\n}\n```\n\n### Step 5: Configure the Test Application\n\nSet up the test application to use your plugin. Open `.dev/package.json` and add your plugin as a file dependency. **Important:** make sure the package name that you use here matches the `name` you defined in your package's `package.json`!\n\n```jsonc\n \"dependencies\": {\n \"@astrojs/node\": \"^9.0.2\",\n \"@astrojs/react\": \"^4.2.0\",\n \"@types/react\": \"^19.0.8\",\n \"@types/react-dom\": \"^19.0.3\",\n \"react\": \"^19.0.0\",\n \"react-dom\": \"^19.0.0\",\n // Add this\n \"@performant/plugin-hello-world\": \"file:../\"\n }\n```\n\nEdit the Astro configuration in `.dev/astro.config-mjs`. Again using the correct name as stated [above](#step-5-configure-the-test-application)\n\n```diff\nimport { defineConfig } from 'astro/config';\nimport react from '@astrojs/react';\nimport node from '@astrojs/node';\n\n+ import HelloWorldPlugin from '@performant/plugin-hello-world';\n\nexport default defineConfig({\n integrations: [\n react(),\n+ HelloWorldPlugin()\n ],\n devToolbar: {\n enabled: false\n },\n adapter: node({\n mode: 'standalone'\n })\n});\n```\n\n### Step 6: Create a UI Extension\n\nNext we'll add a **React component** that displays a \"Hello World\" message in the annotation editor. Inside your `src` directory, create a subdirectory name `extensions` and create a new file `HelloWorldMessage.tsx`\n\n```tsx\n// ./src/extensions/HelloWorldMessage.tsx\n\nexport const HelloWorldMessage = () => {\n return Manual Project Creation
\n\n### Step 1: Initialize a New Plugin Project\n\nCreate a new directory for your plugin and initialize an npm project:\n\n```sh\nmkdir plugin-hello-world\ncd plugin-hello-world\nnpm init\n```\n\nInstall the following dev dependencies:\n\n```sh\nnpm install --save-dev @types/node @types/react @types/react-dom typescript copyfiles\nnpm install --save-dev astro react react-dom\n```\n\nThen, install the Recogito Studio SDK as runtime dependencies:\n\n```sh\nnpm install @recogito/studio-sdk\n```\n\n### Step 2: Configure TypeScript\n\nCreate a tsconfig.json file in your project root:\n\n```json\n{\n \"compilerOptions\": {\n \"allowJs\": true,\n \"allowSyntheticDefaultImports\": true,\n \"baseUrl\": \".\",\n \"declaration\": true,\n \"declarationMap\": true,\n \"isolatedModules\": true,\n \"jsx\": \"react-jsx\",\n \"lib\": [\"ESNext\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ESNext\",\n \"moduleResolution\": \"bundler\",\n \"outDir\": \"dist\",\n \"resolveJsonModule\": true,\n \"skipLibCheck\": true,\n \"strict\": true,\n \"target\": \"ESNext\"\n },\n \"include\": [\"src\", \"test\"],\n \"exclude\": [\"node_modules\", \"dist\"]\n}\n```\n\nMake sure the following lines are in your `package.json`:\n\n```jsonc\n{\n // ...\n \"type\": \"module\",\n \"files\": [\"dist\"],\n \"scripts\": {\n \"build\": \"tsc && npm run copy-files\",\n \"copy-files\": \"copyfiles -u 1 \\\"src/extensions/**/*.css\\\" \\\"src/extensions/**/*.jpg\\\" \\\"src/extensions/**/*.png\\\" dist\"\n }\n}\n```\n\nHello World
;\n};\n```\n\nWe'll configure our plugin so that it exports this React component for the `annotation:*:annotation-editor` extension point. This extension point is a slot at the bottom of the annotation editor.\n\nEdit your `index.ts` file to register the component as a UI extension:\n\nBe sure that `module_name` matches the `name` in your `package.json` file.\n\n```diff\nimport type { AstroIntegration } from 'astro';\nimport { Plugin, registerPlugin } from '@recogito/studio-sdk';\n\nconst HelloWorldPlugin: Plugin = {\n\n name: 'My Hello World Plugin',\n\n module_name: '@performant/plugin-hello-world',\n\n description: 'An example Hello World plugin.',\n\n author: 'Performant Software',\n\n homepage: 'https://www.performantsoftware.com/',\n\n+ extensions: [{\n+ name: 'hello-world-message',\n+\n+ component_name: 'HelloWorldMessage',\n+\n+ extension_point: 'annotation:*:annotation-editor'\n+ }]\n\n};\n\nconst plugin = (): AstroIntegration => ({\n name: 'plugin-hello-world',\n hooks: {\n 'astro:config:setup': ({ config, logger }) => {\n registerPlugin(HelloWorldPlugin, config, logger);\n }\n }\n});\n\nexport default plugin;\n```\n\nFinally: your plugin's `package.json` must expose each UI extension as a sub-module. Add this to your `package.json`:\n\n```jsonc\n{\n // ...\n \"exports\": {\n // Main module entry point – the default Astro Integration export\n \".\": \"./dist/index.js\",\n // Module export for the HelloWorldMessage UI extension\n \"./HelloWorldMessage\": \"./dist/extensions/HelloWorldMessage.js\"\n }\n}\n```\n\nCongratulations. This sets up the foundation for your plugin!\n\nIn your `.dev` directory:\n\n- Run `npm install`.\n\nIn your project directory:\n\n- Run `npm run build` to build your plugin.\n- Run `npm run dev` to start the test application.\n\n### Step 7: Adding a Gallery Thumbnail\n\nWe recommend adding a thumbnail image to your plugin. Recogito Studio will use it to represent your\nplugin in the Plugin Gallery. The thumbnail image can be a JPEG or PNG image with a size of 480 x 480 pixels. You can find a suitable placeholder [here](./images/gallery-thumbnail.png).\n\n![\"The](\"./images/gallery-thumbnail-example.png\")
\n\n1. **Add the thumbnail image file to your project**. You can add the image anywhere in your plugin's `src` folder. A common convention is to put into an `assets` folder, for example:\n\n```\nsrc/assets/thumbnail.png\n```\n2. **Create an export in your package.json**. Edit your `package.json` file to export your thumbnail file.\n\n```jsonc\n{\n // ...\n \"exports\": {\n // Main module entry point – the default Astro Integration export\n \".\": \"./dist/index.js\",\n // Module export for the HelloWorldMessage UI extension\n \"./HelloWorldMessage\": \"./dist/extensions/HelloWorldMessage.js\",\n // Thumbnail export\n \"./thumbnail.png\": \"./dist/assets/thumbnail.png\"\n }\n}\n```\n\n3. **Update your plugin configuration**. Edit the plugin metadata in `src/index.ts` file to match the\nexport in your `package.json`. \n\n```diff\nimport type { AstroIntegration } from 'astro';\nimport { Plugin, registerPlugin } from '@recogito/studio-sdk';\n\nconst HelloWorldPlugin: Plugin = {\n\n name: 'My Hello World Plugin',\n\n module_name: '@performant/plugin-hello-world',\n\n description: 'An example Hello World plugin.',\n\n author: 'Performant Software',\n\n homepage: 'https://www.performantsoftware.com/',\n\n+ thumbnail: 'thumbnail.png',\n\n extensions: [{\n name: 'hello-world-message',\n\n component_name: 'HelloWorldMessage',\n\n extension_point: 'annotation:*:annotation-editor'\n }]\n\n};\n\n// ...\n```\n\n## Test Your Extension\n\nAt this point, you have a–basic, but fully functional–Recogito Studio plugin. Before deploying to Recogito, let's test it in the SDK test application.\n\n- Build your plugin package.\n\n```bash\nnpm run build\n```\n\n- Add your plugin package to the test application as a dependency. (We can do this without publishing the package, by usinga local file link.) Add the following to your `.dev/package.json`:\n\n```jsonc\n{\n //...\n \"dependencies\": {\n //...\n \"@performant/plugin-hello-world\": \"file:../\"\n }\n}\n```\n\n- Configure the test app to use the Astro Integration exposed by your package. Add the following to your `.dev/astro.config.mjs`:\n\n```js\nimport { defineConfig } from \"astro/config\";\nimport react from \"@astrojs/react\";\nimport node from \"@astrojs/node\";\n\n// This imports the plugin to the Astro config\nimport HelloWorldPlugin from \"@performant/plugin-hello-world\";\n\nexport default defineConfig({\n integrations: [\n react(),\n // Add the plugin here\n HelloWorldPlugin(),\n ],\n devToolbar: {\n enabled: false,\n },\n adapter: node({\n mode: \"standalone\",\n }),\n});\n```\n\nAlmost done! Now run `npm install`, `npm run dev` and point your browser to