feat: add github storage adapter plugin

Author: nikolvs

.npmrc

@@ -0,0 +1 @@
+ignore-workspace-root-check=true

package.json

@@ -26,29 +26,18 @@
     "payload": "^3.0.0-beta.111"
   },
   "dependencies": {
-    "@payloadcms/ui": "3.0.0-beta.111",
-    "react": "19.0.0-rc-3edc000d-20240926",
-    "react-dom": "19.0.0-rc-3edc000d-20240926"
+    "@payloadcms/plugin-cloud-storage": "3.0.0-beta.111",
+    "octokit": "^4.0.2"
   },
   "devDependencies": {
     "@payloadcms/eslint-config": "3.0.0-beta.97",
     "@types/node": "22.7.5",
-    "@types/react": "npm:types-react@19.0.0-rc.1",
-    "@types/react-dom": "npm:types-react-dom@19.0.0-rc.1",
     "copyfiles": "^2.4.1",
     "next": "15.0.0-canary.173",
     "payload": "3.0.0-beta.111",
-    "react": "19.0.0-rc-3edc000d-20240926",
-    "react-dom": "19.0.0-rc-3edc000d-20240926",
     "rimraf": "^6.0.1",
     "typescript": "5.5.3"
   },
-  "pnpm": {
-    "overrides": {
-      "@types/react": "npm:types-react@19.0.0-rc.1",
-      "@types/react-dom": "npm:types-react-dom@19.0.0-rc.1"
-    }
-  },
   "publishConfig": {
     "main": "./dist/index.js",
     "registry": "https://registry.npmjs.org/",

pnpm-lock.yaml

@@ -1,3 +1,3 @@
 packages:
   - './'
-  - './dev'
+  # - './dev'

pnpm-workspace.yaml

@@ -0,0 +1,15 @@
+import type { GenerateURL } from '@payloadcms/plugin-cloud-storage/types'
+
+import path from 'node:path'
+
+interface Args {
+  owner: string
+  repo: string
+  branch: string
+}
+
+export const getGenerateURL = ({ branch, owner, repo }: Args): GenerateURL => {
+  return ({ filename, prefix = '' }) => {
+    return `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/${path.posix.join(prefix, filename)}`
+  }
+}

src/generateURL.ts

@@ -0,0 +1,40 @@
+import type { HandleDelete } from '@payloadcms/plugin-cloud-storage/types'
+import type { GithubAuthor } from './types'
+
+import { Octokit } from 'octokit'
+import path from 'node:path'
+
+import { getFileSHA } from './utilities'
+
+interface Args {
+  owner: string
+  repo: string
+  branch: string
+  committer?: GithubAuthor
+  author?: GithubAuthor
+  getStorageClient: () => Octokit
+}
+
+export const getHandleDelete = ({
+  getStorageClient,
+  committer,
+  author,
+  owner,
+  repo,
+  branch,
+}: Args): HandleDelete => {
+  return async ({ doc: { prefix = '' }, filename }) => {
+    const sha = await getFileSHA(getStorageClient, owner, repo, branch, prefix, filename)
+
+    await getStorageClient().rest.repos.deleteFile({
+      committer,
+      author,
+      owner,
+      repo,
+      branch,
+      sha,
+      path: path.posix.join(prefix, filename),
+      message: `:x: Delete "${filename}"`,
+    })
+  }
+}

src/handleDelete.ts

@@ -0,0 +1,43 @@
+import type { HandleUpload } from '@payloadcms/plugin-cloud-storage/types'
+import type { GithubAuthor } from './types'
+
+import { Octokit } from 'octokit'
+import path from 'node:path'
+
+import { getFileSHA } from './utilities'
+
+interface Args {
+  owner: string
+  repo: string
+  branch: string
+  prefix?: string
+  committer?: GithubAuthor
+  author?: GithubAuthor
+  getStorageClient: () => Octokit
+}
+
+export const getHandleUpload = ({
+  getStorageClient,
+  committer,
+  author,
+  owner,
+  repo,
+  branch,
+  prefix = '',
+}: Args): HandleUpload => {
+  return async ({ data, file }) => {
+    const sha = await getFileSHA(getStorageClient, owner, repo, branch, prefix, file.filename)
+
+    await getStorageClient().rest.repos.createOrUpdateFileContents({
+      committer,
+      author,
+      owner,
+      repo,
+      branch,
+      sha,
+      path: path.posix.join(data.prefix || prefix, file.filename),
+      content: file.buffer.toString('base64'),
+      message: data.commitMessage || `:arrow_up_small: Upload "${file.filename}"`,
+    })
+  }
+}

src/handleUpload.ts

@@ -1,2 +1,2 @@
-export { myPlugin } from './plugin.js'
-export type { MyPluginOptions } from './types.js'
+export { githubStorage } from './plugin.js'
+export type { GithubStorageOptions } from './types.js'

src/index.ts

@@ -1,10 +1,109 @@
-import type { Config } from 'payload'
+import type { Config, Plugin } from 'payload'
+import type {
+  Adapter,
+  CollectionOptions,
+  GeneratedAdapter,
+  PluginOptions as GithubStoragePluginOptions,
+} from '@payloadcms/plugin-cloud-storage/types'
+import type { GithubStorageOptions } from './types.js'
 
-import type { MyPluginOptions } from './types.js'
+import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage'
+import { Octokit } from 'octokit'
 
-export const myPlugin =
-  (_: MyPluginOptions) =>
+import { getGenerateURL } from './generateURL.js'
+import { getHandleDelete } from './handleDelete.js'
+import { getHandleUpload } from './handleUpload.js'
+import { getStaticHandler } from './staticHandler.js'
+
+type GithubStoragePlugin = (githubStorageArgs: GithubStorageOptions) => Plugin
+
+export const githubStorage: GithubStoragePlugin =
+  (githubStorageOptions: GithubStorageOptions) =>
   (incomingConfig: Config): Config => {
-    const config = { ...incomingConfig }
-    return config
+    if (githubStorageOptions.enabled === false) {
+      return incomingConfig
+    }
+
+    const adapter = githubStorageInternal(githubStorageOptions)
+
+    // Add adapter to each collection option object
+    const collectionsWithAdapter: GithubStoragePluginOptions['collections'] = Object.entries(
+      githubStorageOptions.collections,
+    ).reduce(
+      (acc, [slug, collOptions]) => ({
+        ...acc,
+        [slug]: {
+          ...(collOptions === true ? {} : collOptions),
+          adapter,
+        },
+      }),
+      {} as Record<string, CollectionOptions>,
+    )
+
+    // Set disableLocalStorage: true for collections specified in the plugin options
+    const config = {
+      ...incomingConfig,
+      collections: (incomingConfig.collections || []).map((collection) => {
+        if (!collectionsWithAdapter[collection.slug]) {
+          return collection
+        }
+
+        return {
+          ...collection,
+          upload: {
+            ...(typeof collection.upload === 'object' ? collection.upload : {}),
+            disableLocalStorage: true,
+          },
+        }
+      }),
+    }
+
+    return cloudStoragePlugin({
+      collections: collectionsWithAdapter,
+    })(config)
+  }
+
+function githubStorageInternal({
+  owner,
+  repo,
+  options,
+  branch = 'main',
+}: GithubStorageOptions): Adapter {
+  return ({ collection, prefix }): GeneratedAdapter => {
+    let storageClient: Octokit | null = null
+
+    const getStorageClient = (): Octokit => {
+      if (storageClient) {
+        return storageClient
+      }
+
+      storageClient = new Octokit(options)
+      return storageClient
+    }
+
+    return {
+      name: 'github',
+      generateURL: getGenerateURL({ branch, owner, repo }),
+      handleDelete: getHandleDelete({
+        getStorageClient,
+        owner,
+        repo,
+        branch,
+      }),
+      handleUpload: getHandleUpload({
+        getStorageClient,
+        owner,
+        repo,
+        branch,
+        prefix,
+      }),
+      staticHandler: getStaticHandler({
+        owner,
+        repo,
+        branch,
+        collection,
+        getStorageClient,
+      }),
+    }
   }
+}

src/plugin.ts

@@ -0,0 +1,57 @@
+import type { CollectionConfig } from 'payload'
+import type { StaticHandler } from '@payloadcms/plugin-cloud-storage/types'
+
+import { Octokit, RequestError } from 'octokit'
+import path from 'node:path'
+
+import { getFileProperties } from './utilities'
+
+interface Args {
+  owner: string
+  repo: string
+  branch: string
+  collection: CollectionConfig
+  getStorageClient: () => Octokit
+}
+
+export const getStaticHandler = ({
+  collection,
+  owner,
+  repo,
+  branch,
+  getStorageClient,
+}: Args): StaticHandler => {
+  return async (req, { params: { filename } }) => {
+    try {
+      const { prefix, mimeType } = await getFileProperties({ collection, filename, req })
+      const { data, headers } = await getStorageClient().rest.repos.getContent({
+        owner,
+        repo,
+        ref: branch,
+        path: path.posix.join(prefix, filename),
+      })
+
+      const bodyBuffer = 'content' in data ? Buffer.from(data.content, 'base64') : ''
+
+      return new Response(bodyBuffer, {
+        headers: new Headers({
+          'Content-Type': mimeType || 'application/octet-stream',
+          ...('size' in data && {
+            'Content-Length': String(data.size),
+          }),
+          ...('etag' in headers && {
+            ETag: headers.etag,
+          }),
+        }),
+        status: 200,
+      })
+    } catch (err: unknown) {
+      if (err instanceof RequestError && err.status === 404) {
+        return new Response(null, { status: 404, statusText: 'Not Found' })
+      }
+
+      req.payload.logger.error({ err, msg: 'Unexpected error in staticHandler' })
+      return new Response('Internal Server Error', { status: 500 })
+    }
+  }
+}

src/staticHandler.ts

@@ -1,4 +1,48 @@
-export type MyPluginOptions = {
-  debug?: boolean
+import type { CollectionOptions } from '@payloadcms/plugin-cloud-storage/types'
+import { Octokit } from 'octokit'
+
+type OctokitOptions = ConstructorParameters<typeof Octokit>[0]
+
+export interface GithubStorageOptions {
+  /**
+   * The name of the repository owner (GitHub username or organization).
+   */
+  owner: string
+
+  /**
+   * The repository name.
+   */
+  repo: string
+
+  /**
+   * Which branch to upload/read files.
+   *
+   * Default: "main"
+   */
+  branch?: string
+
+  /**
+   * Collection options to apply the GitHub adapter to.
+   */
+  collections: Record<string, Omit<CollectionOptions, 'adapter'> | true>
+
+  /**
+   * Whether or not to enable the plugin.
+   *
+   * Default: true
+   */
   enabled?: boolean
+
+  /**
+   * Octokit client configuration.
+   *
+   * @see https://github.com/octokit/octokit.js
+   */
+  options: OctokitOptions
+}
+
+export interface GithubAuthor {
+  name: string
+  email: string
+  date?: string
 }