Call Local API from another process

[unonweb]

Hello,

just to confirm that this is not possible:
Can I use the Local API from another process (Static Site Generator) running on the same machine?

[jmikrut]

Sure can! Payload just has to be initialized first. As long as you can initialize Payload, you can use its local API.

[unonweb]

Hi James,
thank you for your answer.
I've already tried to init Payload in my script this way:

const start = async () => {
	await payload.init({
		secret: 'somestring',
		mongoURL: 'mongodb://localhost:27017/payloadcms',
		local: true
	})
}
start()

But what I get is:
Error: cannot find Payload config. Please create a configuration file located at the root of your current working directory called "payload.config.js" or "payload.config.ts".

I don't get how to do it. Am I supposed to move the Local API script (together with my Static Site Generator) into Payload's project folder so it has access to the config, etc?

[DanRibbens]

Instead of moving your scripts to be near your config, you can set the path to your config using the env var: PAYLOAD_CONFIG_PATH. You can either load your env vars from dotenv or as part of the script or with cross-env for OS compatibility right in the package.json scripts.
For example:

// package.json

"scripts": {
"generate:types": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload generate:types",`
},

Does that help?
We should update that error to call out PAYLOAD_CONFIG_PATH.

[unonweb]

Thank you for your support. In the end I couldn't get it to work because my the Static Site Generator Eleventy (that should use Payload's Local API) is build upon CommonJS modules while I'm using ESModules for Payload.

[willviles]

@jmikrut @DanRibbens Just wondering if there's a bigger feature to be implemented here?

The optimal Payload DX is to deploy your CMS anywhere and then reliably expose the Payload Local API & types across package/service boundaries.

Sure, you can cram everything into a Next.js project by using Payload Local API via a custom Next.js server example, or next-payload, but each of those come with tradeoffs. On one hand you can't deploy properly to Vercel and on the other you get gnarly cold starts on your CMS.

Could a payload build-client method be a solution?

It could build a @my-scope/payload-client package as a subfolder within the Payload project. From there, monorepos can just point to it as a workspace package and use it in consuming services as a proper dependency. Multi-repo setups could publish it to their own npm scope for consumption in other repos.

I anticipate that for most use cases, the method of just pointing PAYLOAD_CONFIG_PATH at the config isn't viable. Firstly, it obviously doesn't work at all for multi-repo setups, but also doesn't work (without deploy-time jiggery pokery) for popular monorepo solutions like Turborepo, as they automatically prune away any non-declared dependencies when building & deploying a service.

There's also the issue @unonweb detailed above, whereby CommonJS and ESModules don't play nicely together and may be incompatible between Payload & the consuming app.

The generated package could also handle local API connection management, which is presently a problem in the latest versions of Next.js and export all generated types, therein providing a better solution than having to set TS aliases for consuming them via payload/generated-types.

This would be delicious:

import { 
  getPayloadClient 
  /*, type Page */ 
} from '@my-scope/payload-client'

const getPage = cache(async (path: string) => {
  const payload = await getPayloadClient()

  const { docs } = await payload.find({
    collection: 'pages',
    where: {
      path: {
        equals: path
      }
    }
  })

  const page = docs[0] // Type is automatically inferred as Page

  try {
    if (!page) throw new Error('Page not found')
  } catch (err) {
    return notFound()
  }

  return page
})

export default async function FooPage () {
  const page = await getPage('/foo')

  return (
    <header>
        <h1>{page.title}</h1>
    </header>
  )
}