feat: add algolia search support #34
Conversation
JounQin
added
enhancement
🦋 Changeset detectedLatest commit: bfacf62 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
WalkthroughThe changes introduce Algolia search integration into the project. This includes configuration updates, CLI enhancements, conditional theme logic for search, and type extensions to support Algolia options. Supporting updates add relevant dependencies, environment variable handling, and documentation for crawler verification. A new theme export and TypeScript path alias are also included. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CLI
participant ConfigLoader
participant Env
participant Theme
User->>CLI: Run with --algolia flag
CLI->>ConfigLoader: loadConfig({ algolia: true })
ConfigLoader->>Env: Inject ALGOLIA_* env vars if algolia enabled
CLI->>Theme: Start app with env
Theme->>Env: Check ALGOLIA_* env vars
alt All ALGOLIA_* vars present
Theme->>User: Render AlgoliaSearch
else
Theme->>User: Render DefaultSearch
end
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
commit: |
Signed-off-by: JounQin <admin@1stg.me>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/public/Robots.txt (1)
1-1: Consider using lowercase filename for web standards compliance.The file is named
Robots.txtwith a capital 'R', but web standards typically expectrobots.txtin lowercase. Most web crawlers and search engines expect the lowercase version.Consider renaming the file to
robots.txtto ensure better compatibility with web standards and crawler expectations.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
yarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (9)
docs/public/Robots.txt(1 hunks)doom.config.yml(2 hunks)package.json(4 hunks)src/cli/index.ts(1 hunks)src/cli/load-config.ts(5 hunks)src/theme.tsx(1 hunks)src/types.ts(3 hunks)theme/index.ts(1 hunks)tsconfig.json(1 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (1)
src/cli/index.ts (1)
src/cli/helpers.ts (1)
parseBoolean(10-11)
🪛 ESLint
src/theme.tsx
[error] 1-1: Unable to resolve path to module '@rspress/core/theme'.
(import-x/no-unresolved)
[error] 2-2: Unable to resolve path to module '@rspress/plugin-algolia/runtime'.
(import-x/no-unresolved)
[error] 20-20: Unable to resolve path to module '@rspress/core/theme'.
(import-x/no-unresolved)
🔇 Additional comments (15)
tsconfig.json (1)
15-16: LGTM! Path mapping follows existing conventions.The new TypeScript path alias
@alauda/doom/themeproperly follows the existing pattern and correctly points to the theme module. This will enable clean imports of the theme components.theme/index.ts (1)
1-1: LGTM! Clean barrel export pattern.This file correctly implements a barrel export pattern, providing a clean public interface for the theme module. The re-export aligns well with the TypeScript path mapping added in
tsconfig.json.src/cli/index.ts (1)
106-111: LGTM! CLI option follows established patterns.The new Algolia CLI option is properly implemented:
- Uses the existing
parseBooleanhelper function consistently with other boolean options- Has a clear, descriptive help text
- Appropriately defaults to
false- Follows the established option ordering and formatting
doom.config.yml (2)
4-8: LGTM: Clean configuration reorganization.The themeConfig section has been appropriately moved for better organization while maintaining the same content structure.
34-37: LGTM: Proper Algolia configuration structure.The algolia section follows the expected structure with all required keys (appId, apiKey, indexName) matching the AlgoliaOptions type definition. Empty values are appropriate for configuration templates.
src/theme.tsx (1)
1-2:Details
❓ Verification inconclusive
Verify import resolution for Algolia dependencies.
The static analysis tools are reporting import resolution errors for the rspress modules. Please ensure these dependencies are properly installed and the import paths are correct.
🏁 Script executed:
#!/bin/bash # Description: Verify that the Algolia plugin and core theme exports exist # Expected: Both modules should be resolvable and export the expected components # Check if the Algolia plugin is installed and has the runtime export fd -t f "package.json" | xargs -I {} dirname {} | head -1 | xargs -I {} find {} -name "node_modules" -type d | head -1 | xargs -I {} find {} -path "*/@rspress/plugin-algolia/runtime*" -type f # Check if the core theme export exists fd -t f "package.json" | xargs -I {} dirname {} | head -1 | xargs -I {} find {} -name "node_modules" -type d | head -1 | xargs -I {} find {} -path "*/@rspress/core/theme*" -type fLength of output: 471
Verify @rspess/core and @rspess/plugin-algolia installation and exports
I wasn’t able to confirm these imports in this sandbox (no node_modules), so please double-check locally:
- src/theme.tsx (lines 1–2):
import { Search as OriginalSearch } from '@rspess/core/theme' import { Search as AlgoliaSearch } from '@rspess/plugin-algolia/runtime'- Ensure both
@rspess/coreand@rspess/plugin-algoliaappear in your package.json and are installed.- Run locally:
to verify there are no resolution errors.npm ls @rspess/core npm ls @rspess/plugin-algolia- Confirm that each package exports a
Searchcomponent at the specified paths.🧰 Tools
🪛 ESLint
[error] 1-1: Unable to resolve path to module '@rspress/core/theme'.
(import-x/no-unresolved)
[error] 2-2: Unable to resolve path to module '@rspress/plugin-algolia/runtime'.
(import-x/no-unresolved)
src/types.ts (3)
33-33: LGTM: Appropriate CLI option addition.The algolia boolean flag is properly added to GlobalCliOptions interface, maintaining consistency with other optional CLI flags.
45-49: LGTM: Well-defined Algolia configuration interface.The AlgoliaOptions interface correctly defines all required Algolia configuration properties as strings, matching the expected Algolia DocSearch API requirements.
66-66: LGTM: Proper UserConfig extension.The algolia property is appropriately added as optional to the UserConfig interface, allowing users to configure Algolia settings when needed.
package.json (3)
18-18: LGTM: Appropriate theme export addition.The new "./theme" export correctly points to the compiled theme module, enabling external consumption of the custom theme functionality.
68-68: LGTM: Consistent Algolia plugin dependency.The @rspress/plugin-algolia dependency is added with version 2.0.0-beta.8, matching the version of @rspress/core for consistency.
101-101: LGTM: Routine dependency updates.The typescript-eslint and @types/node version updates are minor maintenance updates that should provide bug fixes and improvements.
Also applies to: 115-115
src/cli/load-config.ts (3)
117-117: LGTM: Function signature updatesThe addition of the optional
algoliaparameter to the function signature and type definition is clean and follows the existing pattern.Also applies to: 134-134
346-346: LGTM: Parameter threadingThe
algoliaparameter is correctly threaded through the function call chain fromloadConfigtogetCommonConfig.Also applies to: 426-426
301-309:Details
❓ Verification inconclusive
Verify API key security
The Algolia API key is being exposed as a client-side environment variable. Please ensure this is a search-only API key with read permissions and not an admin API key.
Please confirm that the API key being used here is:
- A search-only API key with restricted permissions
- Safe to expose in client-side code
- Not an admin API key that could be misused
🌐 Web query:
What are the security best practices for exposing Algolia API keys in client-side applications?💡 Result:
Security Best Practices for Exposing Algolia API Keys in Client-Side Applications
Exposing Algolia API keys in client-side applications requires careful attention. While some API keys are intended for public use (like search-only keys), mishandling or misconfiguring them can lead to data leaks or potential misuse. Here’s a breakdown of best practices to minimize your risk:
1. Only Expose Search-Only API Keys on the Client
- Never use Admin or write-access API keys in any client-side code. Only search-only API keys, which permit search queries and not data modification, should be exposed in the frontend[1][2][3][5].
- Admin keys or keys with permissions like
addObject,deleteIndex, oreditSettingsshould be strictly kept on the server and never sent to the browser[2][5].2. Strictly Limit Permissions and Scope
- Ensure every exposed API key has the minimum permissions required—ideally, only
search. Remove all unnecessary permissions[3][5].- Limit the key to specific indices whenever possible, rather than using a global key that accesses all data[2][4].
- Algolia allows you to generate secured API keys with embedded restrictions (scope, filters, rate limits, and expiration) for even finer control[2][4][5].
3. Use HTTP Referrer and Rate Limits
- Restrict API key use to specific HTTP referrers (your web domains) so the key is only valid on your site[1].
- Note: While HTTP referrer restrictions can help, they can be spoofed and are only a partial safeguard.
- Apply sensible rate limits to keys to minimize abuse if they are leaked[1][4].
4. Store and Distribute Keys Securely during Development
- Never hard-code any API keys directly in your source code, even for frontend-only keys; use environment variables or build tools to inject them as needed during deployment[7][8][10].
- Avoid committing any keys to your code repository (even in development), as this risks permanent exposure[8][10].
5. Monitor Key Usage and Rotate Regularly
- Monitor requests made with your keys for unusual or unauthorized activity and set up alerts for anomalies[1][7].
- Rotate (regenerate) your public API keys at least annually—or immediately if you suspect a leak[1][7][8].
6. Use Secure Proxy or Backend when Possible
- If your data is highly sensitive, do not expose any key (even search-only) on the client. Instead, create a backend endpoint (a proxy) that holds the API key securely and relays requests from the client. This ensures the key is never visible to users or attackers[7][9].
- This setup is strongly recommended if you want to enforce authentication, user-level filtering, or hide all API keys from the browser.
7. Use Secrets Management for Sensitive Keys
- Store sensitive keys (like Admin or write-access keys) in secure secrets management solutions (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) and never expose them to the client[8][9].
Summary Table
Best Practice Details/Actions Use Only Search-Only Keys Never expose Admin/write keys; restrict public keys to searchpermissionsEnforce Scope/Restrictions Limit accessible indices, use secured API keys for granular restrictions Referrer/Rate Limits Bind keys to domains and set limits to reduce misuse risk Avoid Hardcoding/Exposure Use environment variables/build tools; never commit keys to source repos Monitor & Rotate Watch for suspicious use; rotate keys regularly Backend Proxy Option For sensitive data, use a backend to keep all keys private Secrets Management Store sensitive keys in vaults or secret managers, not in source/code
Key Takeaways
- Never expose sensitive Algolia API keys (Admin/write-access) on the client—use only strictly limited, search-only keys with strong restrictions[1][2][5][10].
- Harden exposed keys by scoping access, using referer restrictions, rate limits, and monitoring[1][2][4].
- Proactively manage keys: rotate, audit, and use secure storage and distribution methods[1][7][8][10].
Following these practices will significantly reduce the risk of unauthorized data access and incidents from exposed Algolia API keys.
Citations:
- 1: https://www.algolia.com/doc/guides/security/security-best-practices/
- 2: https://www.algolia.com/doc/guides/security/api-keys/
- 3: https://support.algolia.com/hc/en-us/articles/14339249272977-What-are-the-best-practices-to-manage-Algolia-API-keys-in-my-code-and-protect-them
- 4: https://www.algolia.com/doc/guides/security/api-keys/in-depth/api-key-restrictions/
- 5: https://echeloncyber.com/intelligence/entry/hackers-perspective-web-app-vulnerabilities-algolia-api-keys
- 6: https://cloud.google.com/docs/authentication/api-keys-best-practices
- 7: https://dev.to/theudemezue/how-to-secure-an-api-key-in-javascript-51bh
- 8: https://www.gitguardian.com/remediation/algolia-key
- 9: https://strapi.io/blog/how-to-store-API-keys-securely
- 10: https://www.legitsecurity.com/aspm-knowledge-base/api-key-security-best-practices
Verify Algolia API Key Exposure
We’re injecting
process.env.ALGOLIA_API_KEYinto the client bundle. Please confirm the following before shipping:
- It is strictly a search-only key (no write/admin permissions).
- Permissions are scoped to only the indices your frontend needs.
- You’ve applied HTTP referrer restrictions or generated a secured API key with embedded filters/rate limits.
- You’re monitoring usage and have a key-rotation policy in place.
If your use case ever requires more than pure search, or you need to enforce user-level access, route requests through a backend proxy so no key appears in the browser.
There was a problem hiding this comment.
Pull Request Overview
This PR adds support for Algolia-powered search by introducing a new search component, CLI flag, and configuration options, and wiring them into the build process.
- Added an
--algoliaCLI flag and corresponding types for Algolia credentials - Conditionally render the Algolia search component in the theme
- Inject Algolia environment variables into the bundler via DefinePlugin
Reviewed Changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| theme/index.ts | Re-export theme entry point |
| src/types.ts | Add algolia boolean flag and AlgoliaOptions type |
| src/theme.tsx | Conditionally switch between default and Algolia search |
| src/cli/load-config.ts | Destructure algolia, define plugin when enabled |
| src/cli/index.ts | Add -a, --algolia CLI option |
| package.json | Export theme, bump dependencies |
| doom.config.yml | Add themeConfig block and algolia placeholders |
| docs/public/Robots.txt | Add Algolia crawler verification comment |
| .changeset/witty-carrots-repair.md | Record minor update for Algolia feature |
Summary by CodeRabbit
New Features
Chores