{"id":14808,"library":"perlnavigator-server","title":"Perl Navigator Language Server","description":"Perl Navigator is an actively developed Language Server Protocol (LSP) implementation providing advanced code intelligence for Perl. Currently at version 0.8.20, it is designed to work across various operating systems (Windows, macOS, Linux) and integrates with popular editors supporting LSP, such as VS Code, Neovim, Emacs, and Sublime Text. It offers features like syntax checking, smart context-aware autocompletion, 'Go To Definition' (including core and installed modules), code formatting via Perl::Tidy, Perl::Critic static analysis, and imports cleanup via perlimports. A key differentiator is its broad Perl version compatibility, working back to Perl 5.8, and its robust parsing capabilities for modern Perl features and class builders like Moo/Moose/Object::Pad. While the core server is written in TypeScript and Node.js, its primary function is to enhance the Perl development experience through editor integration, not to be consumed as a JavaScript/TypeScript library directly.","status":"active","version":"0.8.20","language":"javascript","source_language":"en","source_url":"https://github.com/bscan","tags":["javascript","perl","lsp","languageserver"],"install":[{"cmd":"npm install perlnavigator-server","lang":"bash","label":"npm"},{"cmd":"yarn add perlnavigator-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add perlnavigator-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Perl Navigator leverages the Perl interpreter itself for syntax checking, parsing, and executing tools like Perl::Critic and Perl::Tidy. A functional Perl installation is mandatory for the server to operate.","package":"perl","optional":false},{"reason":"Provides static code analysis and suggestions. While Perl Navigator supports its integration, the module itself is not bundled and must be installed separately via CPAN for this feature to work.","package":"Perl::Critic","optional":true},{"reason":"Enables code formatting capabilities. Similar to Perl::Critic, this module needs to be installed independently via CPAN.","package":"Perl::Tidy","optional":true},{"reason":"Offers diagnostics for imports cleanup. This Perl module is an optional dependency for its specific functionality.","package":"perlimports","optional":true}],"imports":[],"quickstart":{"code":"{\n  \"languageserver\": {\n    \"perl\": {\n      \"command\": \"perlnavigator\",\n      \"args\": [\"--stdio\"],\n      \"filetypes\": [\"perl\", \"cperl\", \"pl\", \"pm\", \"t\", \"cgi\", \"psgi\"],\n      \"rootPatterns\": [\n        \"cpanfile\",\n        \"META.json\",\n        \"META.yml\",\n        \".git\",\n        \"perlnavigator.json\"\n      ],\n      \"settings\": {\n        \"perlnavigator.perlPath\": \"/usr/bin/perl\",\n        \"perlnavigator.includePaths\": [\"$workspaceFolder/lib\"],\n        \"perlnavigator.perlcriticEnabled\": true\n      }\n    }\n  }\n}","lang":"json","description":"Demonstrates a typical LSP client configuration for Perl Navigator, showing how to invoke the server executable and configure basic settings like Perl path and include directories. This is how editors interact with the server."},"warnings":[{"fix":"Interact with Perl Navigator by configuring your code editor's LSP client to run the `perlnavigator` executable, typically installed globally via npm. Do not attempt to import it as a library in your JavaScript/TypeScript code.","message":"Perl Navigator is a Language Server, an executable application, not a traditional JavaScript/TypeScript library designed for programmatic imports into other Node.js projects. Its interaction model is via the Language Server Protocol (LSP) through editor integrations. Attempting to `import` or `require` symbols directly from the `perlnavigator-server` package will likely result in unexpected behavior or errors, as its main export is the server's entry point, not a library API.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install required Perl modules using CPAN (e.g., `cpanm Perl::Critic Perl::Tidy perlimports`) and ensure your Perl environment is correctly configured and accessible by the server.","message":"For features like static analysis (Perl::Critic), code formatting (Perl::Tidy), and imports cleanup (perlimports), the corresponding Perl modules are NOT bundled with `perlnavigator-server`. These modules must be installed separately via CPAN on your system for Perl Navigator to utilize them.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set the `perlnavigator.perlPath` configuration option to the full, absolute path of your Perl executable (e.g., `\"/home/user/perl5/perlbrew/perls/perl-5.38.2/bin/perl\"`). Avoid aliases or relative paths.","message":"If Perl is installed in a non-standard location or if you are using a Perl environment manager (like `perlbrew`), you might need to explicitly configure the `perlnavigator.perlPath` setting in your editor's LSP client. The server might fail to find your Perl executable, leading to non-functional language features.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use LSP client settings to define `perlnavigator.perlPath` and an array of `perlnavigator.includePaths` (which map to Perl's `@INC`). For containerized setups, this often involves careful path mapping or custom wrapper scripts for `perlPath`. The `$workspaceFolder` variable can be used in `includePaths` to reference project roots.","message":"When developing in environments with specialized Perl setups, such as Docker containers or complex multi-root workspaces, Perl Navigator might not find custom modules. It's crucial to correctly configure `perlnavigator.perlPath` and `perlnavigator.includePaths` to reflect the Perl environment and module directories within your project.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure you save your Perl file before expecting `perlimports` features (like diagnostics or formatting) to reflect the latest changes. This is standard behavior for this specific feature.","message":"The `perlimports` feature, used for cleaning up imports, requires the file you are working on to be saved to disk for accurate results due to implementation limitations. Real-time updates for `perlimports` diagnostics might not occur until after a save action.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"After cloning and running `npm install`, navigate to the `server/` directory and execute `npx tsc` to compile the server code. Then, you can reference `server/out/server.js` when configuring your LSP client.","message":"If you are installing Perl Navigator from source by cloning the GitHub repository, merely running `npm install` in the root might not be sufficient. The TypeScript source code for the server (`server/src/server.ts`) needs to be compiled to JavaScript (`server/out/server.js`) using `npx tsc` within the `server/` directory before the server executable is available.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `sudo npm install -g perlnavigator-server` to install globally, or ensure the installation directory is added to your system's PATH environment variable. If installing from source, ensure `npx tsc` was run in the `server/` directory and your editor configuration points to the correct `server/out/server.js` path.","cause":"The `perlnavigator` executable is not in your system's PATH, or the global npm install failed or was not performed.","error":"command not found: perlnavigator"},{"fix":"Verify and set the `perlnavigator.perlPath` setting in your editor's LSP configuration to the absolute path of your Perl executable. Also, add directories containing your project's Perl modules to `perlnavigator.includePaths` (e.g., `\"perlnavigator.includePaths\": [\"$workspaceFolder/lib\", \"/path/to/cpan_modules\"]`).","cause":"The Perl Navigator server is running but cannot find your Perl executable or is not correctly resolving Perl modules due to incorrect include paths.","error":"No Syntax Highlighting, nor Code completion. Also the imported Scalar Package is not recognised."},{"fix":"Install the necessary Perl modules via CPAN (e.g., `cpanm Perl::Critic Perl::Tidy perlimports`). Additionally, check your editor's LSP settings for `perlnavigator.perlcriticEnabled`, `perlnavigator.perlcriticProfile`, `perlnavigator.perltidyProfile`, and `perlnavigator.perlimportsProfile` to ensure they are enabled and point to valid profile files if custom ones are used.","cause":"The Perl modules `Perl::Critic`, `Perl::Tidy`, or `perlimports` are either not installed on your system or the Perl Navigator configuration for their profiles is incorrect.","error":"Perl::Critic diagnostics or Perl::Tidy formatting not working, or 'perlimports' does not clean up code."}],"ecosystem":"npm"}