From 72126a18d120b20aa2298a68fe09869368430ddf Mon Sep 17 00:00:00 2001 From: Ahad Birang Date: Tue, 16 Aug 2022 11:04:52 +0200 Subject: [PATCH 1/3] docs: document transformers --- docs/content/4.api/4.advanced.md | 69 +++++++++++++++++++ .../transformer/content/1.index.names | 4 ++ .../transformer/my-module/my-module.ts | 14 ++++ .../transformer/my-module/my-transformer.ts | 12 ++++ examples/advanced/transformer/nuxt.config.ts | 9 +++ examples/advanced/transformer/package.json | 14 ++++ .../advanced/transformer/pages/[...slug].vue | 25 +++++++ 7 files changed, 147 insertions(+) create mode 100644 examples/advanced/transformer/content/1.index.names create mode 100644 examples/advanced/transformer/my-module/my-module.ts create mode 100644 examples/advanced/transformer/my-module/my-transformer.ts create mode 100644 examples/advanced/transformer/nuxt.config.ts create mode 100644 examples/advanced/transformer/package.json create mode 100644 examples/advanced/transformer/pages/[...slug].vue diff --git a/docs/content/4.api/4.advanced.md b/docs/content/4.api/4.advanced.md index b7e130a3c..308eab40d 100644 --- a/docs/content/4.api/4.advanced.md +++ b/docs/content/4.api/4.advanced.md @@ -77,3 +77,72 @@ export default defineNitroPlugin((nitroApp) => { }) ``` + +## Transformers + +Transformers are responsible for parsing and manipulating contents in the content module. +Internally, the module has specific transformer for each content type to parse the raw content and prepare it for querying and rendering. + +You can create cusotm transformers to support new content types or perhaps to improve some functionalities of supported content types. + +1. Create your transformer. A transformer consists of 4 parts: + - `name`: Transformer name + - `extensions`: List of valid file extensions + - `parse`: If provided this function will be used to parsed the raw content + - `transform`: Received that parsed content and manipulate the content. + +```ts [my-transformer.ts] +// filename: my-transformer.ts +import { defineTransformer } from '@nuxt/content/transformers' + +export default defineTransformer({ + name: 'my-transformer', + extensions: ['.names'], + parse (_id, rawContent) { + return { + _id, + body: rawContent.trim().split('\n').map(line => line.trim()).sort() + } + } +}) + +``` + +2. Define simple module to register transformer + +```ts [my-module.mjs] +// filename: my-module.mjs +import { resolve } from 'path' +import { defineNuxtModule } from '@nuxt/kit' + +export default defineNuxtModule({ + setup (_options, nuxt) { + nuxt.options.nitro.externals = nuxt.options.nitro.externals || {} + nuxt.options.nitro.externals.inline = nuxt.options.nitro.externals.inline || [] + nuxt.options.nitro.externals.inline.push(resolve('./my-module')) + // @ts-ignore + nuxt.hook('content:context', (contentContext) => { + contentContext.transformers.push(resolve('./my-module/my-transformer.ts')) + }) + } +}) + +``` + +3. Register your module + +```ts [nuxt.config.ts] +// filename: my-module.mjs +import { resolve } from 'path' +import { defineNuxtConfig } from '@nuxt/kit' +import MyModule from './my-module' + +export default defineNuxtConfig({ + modules: [ + MyModule, + '@nuxt/content' + ] +}) +``` + +That's it. You can create `.names` files in content directory. Chechout transformer example. \ No newline at end of file diff --git a/examples/advanced/transformer/content/1.index.names b/examples/advanced/transformer/content/1.index.names new file mode 100644 index 000000000..0b1f1c911 --- /dev/null +++ b/examples/advanced/transformer/content/1.index.names @@ -0,0 +1,4 @@ +John +Joes +Jessi +Jason \ No newline at end of file diff --git a/examples/advanced/transformer/my-module/my-module.ts b/examples/advanced/transformer/my-module/my-module.ts new file mode 100644 index 000000000..ef5733b78 --- /dev/null +++ b/examples/advanced/transformer/my-module/my-module.ts @@ -0,0 +1,14 @@ +import { resolve } from 'path' +import { defineNuxtModule } from '@nuxt/kit' + +export default defineNuxtModule({ + setup (_options, nuxt) { + nuxt.options.nitro.externals = nuxt.options.nitro.externals || {} + nuxt.options.nitro.externals.inline = nuxt.options.nitro.externals.inline || [] + nuxt.options.nitro.externals.inline.push(resolve('./my-module')) + // @ts-ignore + nuxt.hook('content:context', (contentContext) => { + contentContext.transformers.push(resolve('./my-module/my-transformer.ts')) + }) + } +}) diff --git a/examples/advanced/transformer/my-module/my-transformer.ts b/examples/advanced/transformer/my-module/my-transformer.ts new file mode 100644 index 000000000..7e777ce17 --- /dev/null +++ b/examples/advanced/transformer/my-module/my-transformer.ts @@ -0,0 +1,12 @@ +import { defineTransformer } from '@nuxt/content/transformers' + +export default defineTransformer({ + name: 'my-transformer', + extensions: ['.names'], + parse (_id, rawContent) { + return { + _id, + body: rawContent.trim().split('\n').map(line => line.trim()).sort() + } + } +}) diff --git a/examples/advanced/transformer/nuxt.config.ts b/examples/advanced/transformer/nuxt.config.ts new file mode 100644 index 000000000..5795550d6 --- /dev/null +++ b/examples/advanced/transformer/nuxt.config.ts @@ -0,0 +1,9 @@ +import { defineNuxtConfig } from 'nuxt' +import MyModule from './my-module/my-module' + +export default defineNuxtConfig({ + modules: [ + MyModule, + '@nuxt/content' + ] +}) diff --git a/examples/advanced/transformer/package.json b/examples/advanced/transformer/package.json new file mode 100644 index 000000000..3ef862d24 --- /dev/null +++ b/examples/advanced/transformer/package.json @@ -0,0 +1,14 @@ +{ + "name": "example-hello-world", + "private": true, + "scripts": { + "build": "nuxt build", + "dev": "nuxt dev", + "generate": "nuxt generate", + "preview": "nuxt preview" + }, + "devDependencies": { + "@nuxt/content": "npm:@nuxt/content-edge@latest", + "nuxt": "npm:nuxt3@latest" + } +} diff --git a/examples/advanced/transformer/pages/[...slug].vue b/examples/advanced/transformer/pages/[...slug].vue new file mode 100644 index 000000000..2aa84efb3 --- /dev/null +++ b/examples/advanced/transformer/pages/[...slug].vue @@ -0,0 +1,25 @@ + + + + + From af8d0a6f11a86c120b03a21588bb10c42edce004 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Tue, 16 Aug 2022 12:06:26 +0200 Subject: [PATCH 2/3] Update docs/content/4.api/4.advanced.md --- docs/content/4.api/4.advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/4.api/4.advanced.md b/docs/content/4.api/4.advanced.md index 308eab40d..b9c756b9d 100644 --- a/docs/content/4.api/4.advanced.md +++ b/docs/content/4.api/4.advanced.md @@ -83,7 +83,7 @@ export default defineNitroPlugin((nitroApp) => { Transformers are responsible for parsing and manipulating contents in the content module. Internally, the module has specific transformer for each content type to parse the raw content and prepare it for querying and rendering. -You can create cusotm transformers to support new content types or perhaps to improve some functionalities of supported content types. +You can create custom transformers to support new content types or improve functionalities of supported content types. 1. Create your transformer. A transformer consists of 4 parts: - `name`: Transformer name From 5497fbc523f04bd3327ad427760bd09c5b9d0d02 Mon Sep 17 00:00:00 2001 From: Ahad Birang Date: Tue, 16 Aug 2022 14:11:31 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: nobkd <44443899+nobkd@users.noreply.github.com> --- docs/content/4.api/4.advanced.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/4.api/4.advanced.md b/docs/content/4.api/4.advanced.md index b9c756b9d..c28f546a1 100644 --- a/docs/content/4.api/4.advanced.md +++ b/docs/content/4.api/4.advanced.md @@ -81,7 +81,7 @@ export default defineNitroPlugin((nitroApp) => { ## Transformers Transformers are responsible for parsing and manipulating contents in the content module. -Internally, the module has specific transformer for each content type to parse the raw content and prepare it for querying and rendering. +Internally, the module has specific transformers for each content type to parse the raw content and prepare it for querying and rendering. You can create custom transformers to support new content types or improve functionalities of supported content types. @@ -145,4 +145,4 @@ export default defineNuxtConfig({ }) ``` -That's it. You can create `.names` files in content directory. Chechout transformer example. \ No newline at end of file +That's it. You can create `.names` files in content directory. Checkout transformer example. \ No newline at end of file