Skip to content

Latest commit

 

History

History
349 lines (257 loc) · 10.3 KB

config-reference.md

File metadata and controls

349 lines (257 loc) · 10.3 KB

Config Reference

Config File

Cayo is not "zero config" because it does require a particular project structure, but it does support having no config file. However, adding a cayo.config.js file to your project allows you to configure most of the things that Cayo needs & expects, such as paths for pages, components, and even the template filename.

Example

// cayo.config.js
export default {
  // config options
  pages: 'outputs',    // default: 'pages'
  components: 'cayos', // default: 'components'
  build: {
    outDir: 'build',   // default: 'dist'
  },
  svelte: {
    // Svelte options, e.g., for defining preprocessors for svelte.preprocess
  },
  vite: {
    // Vite options, like server.port
    server: {
      port: 1234
    },
    rollupOptions: {
      // Rollup options, like plugins
    }
  }
}

Check out more config examples.

Cayo Options

projectRoot

  • Type: string
  • Default: '.'

The project root directory, where Cayo will look for the required project structure. Can be an absolute path or a directory relative to the current working directory. This folder will be watched for changes during dev.

src

  • Type: string
  • Default: 'src'

Specify the directory where your source files will be, relative to the project root.

pages

  • Type: string
  • Default: 'pages'

Specify the directory where your page components will be, relative to src. These can also just be thought of as "inputs" for the HTML that is generated as output.

components

  • Type: string
  • Default: 'components'

Specify the directory where your Cayo Components will be, relative to src. Cayo will expect any <name>.cayo.svelte that is to be rendered on a page to be in this directory. Other components are not required to be in this directory, but can be.

publicDir

  • Type: string
  • Default: 'public'

Note
Use this option instead of Vite's publicDir option. We pass it to Vite, but also use it internally within Cayo processes.

Specify the directory to be used as the public directory, which is used to serve static assets during development and copied into the build.outDir during build.

This is where your static assets will go, such as images, favicon.ico, and any static JS dependencies.

You will be able to reference any of these assets with a leading / in your markup.

For example: assuming you haven't changed the default, and you have this in your project root:

src/
└ pages/
  └ index.svelte
public/
└ some.png

<!-- index.svelte -->
<img src="/some.png">

Read about how the public directory works in Vite.

base

  • Type: string
  • Default: '/'

Note
Use this option instead of Vite's base option. We pass it to Vite, but also use it internally within Cayo processes.

Base public path when served in development or production.

Since this option is passed to Vite, read more about it in the Vite docs.

build.outDir

  • Type: string
  • Default: 'dist'

Specify the output directory, relative to the project root.

build.assetsDir

  • Type: string
  • Default: 'assets'

Specify where the assets generated by Cayo should be placed within your output, relative to build.outDir.

css.internal

  • Type: boolean
  • Default: false

If set to true, this will inject a page's CSS inside <style> elements, in place of <link> elements.

This will only affect the component-scoped CSS you define in a Svelte component (or page), and any CSS imported in an entry file.

cayoPath

  • Type: string
  • Default: '.cayo'

Specify the Cayo output directory that is used for Cayo processes. Cayo outputs files into this folder, and it's contents are either served during cayo dev or used to build your project during cayo build.

cayoComponentInfix

  • Type: string
  • Default: 'cayo'

Specify the Cayo Component infix that is used to identify by Cayo's processes (Note: <name>.<infix>.<extension>). By default, a Cayo looks like: some.cayo.svelte. If you changed this option's value to 'fancy', your Cayo would need to be named some.fancy.svelte.

templateName

  • Type: string
  • Default: '__template'

Specify the name of the template file. This is not a path; Cayo will always expect this filename to be at the root of the src directory (e.g., src/__template.svelte). The extension, .svelte should not be included in this option's value.

mode

  • Type: string | false
  • Default: 'development'

By default, the mode will be development during cayo dev and production during cayo build. This option can be used to override the default mode, and will be used for both commands.

debug

  • Type: boolean
  • Default: false

Useful for seeing more output when running cayo.

Note
This option is experimental and may be removed in the future.

Svelte Options

There are a few options that Cayo passes to Svelte (consumed by rollup-plugin-svelte):

Svelte options are passed via the Cayo config:

// cayo.config.js
export default {
  svelte: {
    preprocess: [
      // define custom preprocessors for Svelte to use
    ],
    compilerOptions: {
      // define compiler options for Svelte to use
    }
  }
}

svelte.preprocess

  • Type: <SveltePreprocessor> | Array<SveltePreprocessor>
  • Default: []

Passed to the Svelte Rollup plugin, but is appended to an array of Cayo's internally defined preprocessors (which is only svelte-preprocess). See plugin options.

svelte.compilerOptions

  • Type: object (of options)
  • Default: {}

There are a few options that Cayo needs to control in order to work, so changing them will have no effect: compilerOptions.generate and compilerOptions.hydratable. All other options will be passed to the Svelte Rollup plugin. See plugin options.

Vite Options

Not all Vite options are directly used by Cayo. Most of them are passed to the dev process, which uses vite dev. vite.build.rollupOptions is the only Vite-specific option passed during both cayo dev and cayo build.

Note
Cayo shares some options with Vite, such as publicDir and base and root (as projectRoot). These should be defined at top level of your Cayo config, not in the vite option object, but will be passed to Vite as needed.

Vite options are passed via the Cayo config:

// cayo.config.js
export default {
  vite: {
    server: {
      // server options, like port
    }
    build: {
      // rollupOptions is the only passed vite.build option
      rollupOptions: {
      // define Rollup options to be used for dev and build, like plugins
    },
    // other Vite options...
  }
}

During cayo dev, Cayo defines a few Vite options internally, which cannot be overridden:

  • configFile: false

Rollup Options

Options for Rollup should be passed to Cayo via the vite.build.rollupOptions object. The only Rollup config option that Cayo uses internally is vite.build.rollupOptions.plugins, but the entire rollupOptions object is passed to Vite while running the dev server and during build.

More Examples

Customize svelte-preprocess

To add options to Svelte Preprocess, install svelte-preprocess locally, and then pass the preprocessor(s) in your Cayo config with options:

// cayo.config.js
import sveltePreprocess from 'svelte-preprocess';
export default {
  svelte {
    preprocess: [
      sveltePreprocess({
        // Learn more about the options you can pass here:
        // https://github.com/sveltejs/svelte-preprocess/blob/main/docs/preprocessing.md
        markupTagName: 'content',
        replace: [['Jane', 'Cool'], ['Doe', 'Cat']]
      }),
    ],
  }
}

Add mdsvex

Adding other Svelte preprocessors works similar to how it would in any other Vite + Svelte project.

For example, let's refactor mdsvex's own docs example for customizing extensions.

To import markdown files as components, add .md to both the Svelte compiler and mdsvex extensions:

// cayo.config.js
import { mdsvex } from "mdsvex";
export default {
  // Putting these options inside the svelte option object is the only difference
  svelte: { 
    extensions: ['.svelte', '.svx', '.md'],
    preprocess: [
      mdsvex({ extensions: ['.svx', '.md'] }),
    ],
  }
}

Conditional Config

Cayo doesn't have built-in features to support a conditional config. E.g., say you different config options for cayo dev and cayo build.

However, you can set up your dev environment to support this yourself. Here's an example that uses the NODE_ENV environment variable to swap configs when running cayo:

Define scripts that set the environment while running cayo dev and cayo build

package.json:

"scripts": {
  "dev": "export NODE_ENV=development && cayo dev",
  "build": "export NODE_ENV=production && cayo build"
}

Add conditions in your Cayo config based on the value of NODE_ENV

cayo.config.js:

let config;
if (process.env.NODE_ENV === 'development') {
  config = {
    // development options for `cayo dev`
  }
} else if (process.env.NODE_ENV === 'production') {
  config = {
    // production options for `cayo build`
  }
}

export default config;

Now when you run npm run dev:

  • cayo dev will run but also set NODE_ENV to 'development'
  • the dev config will be used

With this scripts setup, you could also use process.env.NODE_ENV in your components. Say you wanted to have a conditional Template:

__template.svelte:

{#if process.env.NODE_ENV === 'development'}
  <div class="dev">
    I'm running in development mode
  </div>
  %cayo.body%
{:else}
  %cayo.body%
{/if}