螺旋共享 - 配置
配置包为管理各种Helix项目配置提供了一组配置类. 这些类处理来自本地目录或远程 GitHub 寄存器的基于 YAML 的配置文件的加载,校验和管理.
安装
npm install @adobe/helix-shared-config
使用量
IndexConfig - 管理搜索索引
这个 IndexConfig class 管理搜索索引配置,用于内容发现和查询.
import { IndexConfig } from '@adobe/helix-shared-config';
// Load from local file
const config = await new IndexConfig()
.withConfigPath('/path/to/helix-query.yaml')
.init();
// Load from GitHub repository
const config = await new IndexConfig()
.withRepo('owner', 'repo', 'ref')
.init();
// Access index configuration
const indices = config.toJSON().indices;
// Get a specific query
const query = config.getQuery('my-index', 'my-query');
// Get query cache timeout
const cacheTimeout = config.getQueryCache('my-index', 'my-query');
// Generate query URL with parameters
const queryUrl = config.getQueryURL('my-index', 'my-query', 'owner', 'repo', {
page: '1',
filter: 'value'
});
MountConfig - 管理山地点
这个 MountConfig 类管理挂载点配置,将路径映射到OneDrive,Google Drive或GitHub等外部内容源.
import { MountConfig } from '@adobe/helix-shared-config';
// Load mount configuration
const config = await new MountConfig()
.withRepo('owner', 'repo', 'ref')
.init();
// Match a resource path to a mount point
const mountPoint = config.match('/docs/guide');
if (mountPoint) {
console.log(mountPoint.type); // 'onedrive', 'google', or 'github'
console.log(mountPoint.url); // Source URL
console.log(mountPoint.relPath); // Relative path from mount point
}
支持的挂载点类型 :
- 一驾/共享点数字 :
https://*.sharepoint.com/...或者说onedrive:URL( URL) - 谷歌驱动器数字 :
https://drive.google.com/...或者说gdrive:URL( URL) - GitHub 图像数字 :
https://github.com/owner/repo/tree/ref/pathURL( URL)
SchemapConfig - 管理项目
这个 SitemapConfig class 管理 SEO 和内容发现的站点映射配置 .
import { SitemapConfig } from '@adobe/helix-shared-config';
// Load sitemap configuration
const config = await new SitemapConfig()
.withRepo('owner', 'repo', 'ref')
.init();
// Add a new sitemap
const sitemap = config.addSitemap({
name: 'main',
origin: 'https://example.com',
source: '/content',
destination: '/sitemap.xml',
lastmod: 'YYYY-MM-DD'
});
// Add language variants
config.addLanguage('main', {
name: 'en',
source: '/en',
destination: '/en/sitemap.xml',
hreflang: 'en-US',
alternate: 'https://example.com/en'
});
// Update sitemap origin
config.setOrigin('main', 'https://www.example.com');
忽略组合 - 管理忽略模式
这个 IgnoreConfig 类管理类似被忽略的图案 .gitignore。 。 。 .
import { IgnoreConfig } from '@adobe/helix-shared-config';
// Load ignore configuration
const config = await new IgnoreConfig()
.withDirectory('/path/to/project')
.init();
// Check if a path is ignored
const isIgnored = config.ignores('/node_modules/package');
修饰器 Config - 管理元数据修饰器
这个 ModifiersConfig 类管理基于 URL 模式的元数据和页眉修改符.
import { ModifiersConfig } from '@adobe/helix-shared-config/modifiers';
// Parse from a sheet-like structure
const sheet = [
{ url: '/*', key: 'Cache-Control', value: 'max-age=3600' },
{ url: '/blog/*', Title: 'Blog', Description: 'Our blog' },
{ url: '/docs/**', key: 'X-Robots-Tag', value: 'noindex' }
];
const config = ModifiersConfig.fromModifierSheet(sheet);
// Get modifiers for a specific path
const modifiers = config.getModifiers('/blog/post-1');
// Returns: { 'cache-control': 'max-age=3600', 'title': 'Blog', 'description': 'Our blog' }
无服务器函数配置
使用 requiredConfig 或者说 optionalConfig 在无服务器功能中自动加载配置.
import { requiredConfig, optionalConfig } from '@adobe/helix-shared-config';
// Function that requires configuration
async function handler(request, context) {
// Configuration available in context.config
const { fstab, index } = context.config;
const mountPoint = fstab.match(request.url);
// ... process request
}
// Wrap with required config - returns 400 if config is missing
export const main = requiredConfig(handler, 'fstab', 'index');
// Or use optional config - continues without config if missing
export const main = optionalConfig(handler, 'fstab', 'index');
包装器自动取出 owner, (中文(简体) ), repo,以及 ref 从请求参数中加载指定的配置.
配置选项
所有配置类扩展 BaseConfig 并支持下列备选方案:
正在装入配置
const config = await new IndexConfig()
.withDirectory('/path/to/dir') // Set working directory
.withConfigPath('/path/to/config.yaml') // Set explicit config file path
.withSource('yaml: content') // Provide YAML source directly
.withJSON({ key: 'value' }) // Provide parsed JSON directly
.withLogger(logger) // Set custom logger
.init();
从 GitHub 装入
const config = await new IndexConfig()
.withRepo('owner', 'repo', 'ref', {
headers: {
authorization: 'token ghp_...'
}
})
.withTransactionID('request-id-123')
.init();
缓存
const config = await new IndexConfig()
.withCache({ max: 100 }) // Set cache size (max entries)
.withRepo('owner', 'repo', 'ref')
.init();
验证
// Check for parsing errors
const errors = config.getErrors();
if (errors.length > 0) {
console.error('Configuration errors:', errors);
}
配置文件格式
helix-query.yaml (IndexConfig) (英语)
version: 1
indices:
my-index:
include:
- /content/**
exclude:
- /content/drafts/**
target: https://example.algolia.net
properties:
title:
select: head > meta[property="og:title"]
value: attribute(el, 'content')
description:
select: head > meta[name="description"]
value: attribute(el, 'content')
queries:
search:
query: '{search}'
parameters:
- search
hitsPerPage: 10
cache: 600
fstab.yaml (MountConfig) (法语)
mountpoints:
/: https://adobe.sharepoint.com/sites/example/Shared%20Documents/root
/docs: https://github.com/owner/repo/tree/main/documentation
/assets: https://drive.google.com/drive/folders/abc123def456
helix-siteap.yaml (SiteapConfig) (英语)
version: 1
sitemaps:
website:
origin: https://www.example.com
source: /content
destination: /sitemap.xml
lastmod: YYYY-MM-DD
languages:
en:
source: /en
destination: /en/sitemap.xml
hreflang: en-US
alternate: https://www.example.com/en
.hlxignore( IgnoreConfig) (英语)
# Ignore patterns (glob format)
node_modules/
*.tmp
.git/
.DS_Store
高级使用
添加/修改索引定义
const config = await new IndexConfig().init();
// Add a new index
config.addIndex({
name: 'blog',
include: ['/blog/**'],
exclude: ['/blog/drafts/**'],
target: 'https://example.algolia.net',
properties: {
title: { select: 'h1', value: 'textContent(el)' }
}
});
// Replace an existing index
config.replaceIndex({
name: 'blog',
include: ['/blog/**', '/news/**'],
exclude: [],
target: 'https://example.algolia.net',
properties: {}
});
// Remove an index
config.removeIndex({ name: 'blog' });
// Save changes
await config.saveConfig();
使用配置源
// Export to YAML
const yamlString = config.toYAML();
// Export to JSON
const jsonObject = config.toJSON();
// Get raw source
const source = config.source;
// Get version
const version = config.version;
处理错误
配置类包括稳健的错误处理 :
try {
const config = await new IndexConfig()
.withRepo('owner', 'repo', 'ref')
.init();
const errors = config.getErrors();
if (errors.length > 0) {
// Handle YAML parsing errors
errors.forEach(error => console.error(error.message));
}
} catch (e) {
// Handle loading errors
console.error('Failed to load configuration:', e);
}
许可证
阿帕奇 - 2.0