oxc-project/oxc · warning

Relative imports from parent directories are not allowed

Error message

Relative imports from parent directories are not allowed

What it means

Diagnostic from the oxlint rule import/no-relative-parent-imports (restriction category). It fires on any import that reaches into a parent directory via `../`, enforcing a layered architecture where modules may only import downward (their own subtree and packages). The help offers the three standard escapes: move the file, inject the dependency, or package the shared code.

Source

Thrown at crates/oxc_linter/src/rules/import/no_relative_parent_imports.rs:9

use oxc_ast::{AstKind, ast::Expression};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{AstNode, context::LintContext, rule::Rule};

fn no_relative_parent_imports_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Relative imports from parent directories are not allowed")
        .with_help(
            "Move the file to the same directory, use dependency injection, or convert to a package.",
        )
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct NoRelativeParentImports;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Forbids importing modules from parent directories using relative paths.
    ///
    /// ### Why is this bad?
    ///
    /// This restriction enforces tree-like folder structures instead of complex
    /// graph-like structures, making large codebases easier to maintain.

View on GitHub (pinned to e1e7af627c)

Solutions

1. Move the shared code into a common ancestor directory both importers can reach downward, or extract it into a workspace package imported by name
2. Configure path aliases (tsconfig paths / bundler alias) so imports go through a stable package-style specifier instead of ../
3. Invert the dependency: pass the value/function in as a parameter (dependency injection) instead of importing upward
4. If the policy does not fit a corner of the repo, scope the rule off for those paths

Example fix

// before (src/features/auth/session.ts)
import { formatDate } from '../../utils/date';

// after (with tsconfig paths: "@utils/*": ["src/utils/*"])
import { formatDate } from '@utils/date';

// rg -n "from\\s+['\"]\\.\\./" src
// .oxlintrc.json: { "rules": { "import/no-relative-parent-imports": "warn" } }
// tsconfig escape hatch: { "compilerOptions": { "baseUrl": "src", "paths": { "@/*": ["*"] } } }

When it happens

Trigger: Any import whose specifier contains a parent-relative segment (`import x from '../shared/x'`, `../../lib/util`) in a linted file — reported from no_relative_parent_imports_diagnostic at crates/oxc_linter/src/rules/import/no_relative_parent_imports.rs:9.

Common situations: Enforced layering (feature folders that must not reach into siblings via ..); monorepos converting relative webs into package imports; refactors where a file moved deeper and its imports were mechanically updated with ../ prefixes.

Related errors

• Dependency cycle detected
• Could not find the reuseWorker option in ${path}
• Do not assign to imported bindings
• Expected '{curr_kind}' syntax before '{prev_kind}' syntax.
• Imports should be sorted alphabetically.

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/3cb2b27f0e7149bc. Report an issue: GitHub.