A new Next.js-based frontend for the Network Data Exchange (NDEx) platform, providing a user-friendly interface for network biology data management, sharing, and visualization.
NDEx3 is a complete rewrite of the NDEx frontend using web technologies including Next.js, TypeScript, and Tailwind CSS. It is the frontend for managing and organizing networks — uploading, browsing, searching, sharing, and folder-organizing biological network data.
This app does not implement network visualization itself. For certain functions it redirects users to sibling applications, which may be deployed on the same host or a different one, entirely driven by public/config.json:
- Cytoscape Web — "Open in Cytoscape Web" opens the selected network's UUID in the Cytoscape Web application at
<cytoscapeWebUrl>/0/networks/<uuid>. The base URL comes from thecytoscapeWebUrlconfig value (falls back tohttps://web.cytoscape.orgif unset); in this repo's dev config it points at a same-host sibling app (https://dev3.ndex.ucsd.edu/cytoscape). SeeActionDropdown.tsx. - NDEx Network Viewer — legacy hash-router network-viewing links (e.g.
#/network/<uuid>,#/networkset/<uuid>) are redirected client-side to the NDEx Network Viewer, a sibling app deployed on the same host at the/viewer/networks/<uuid>route. The legacypublic.ndexbio.orghost is also canonicalized towww.ndexbio.org, unconditionally and independent of whether the link matches a known legacy pattern. Seesrc/utils/legacyRedirect.ts.
Feature and deployment documentation lives in docs/ — start at docs/README.md for the index, and docs/decisions/ for the architecture decision records.
This app also redirects a few legacy URL shapes from the previous NDEx2 frontend to their NDEx3 equivalents (host canonicalization, hash-fragment rewriting, and a legacy bare-pathname route) — see docs/legacy-redirects.md for the full set of rules and why they're split across two implementations.
- 🔐 Keycloak Authentication - Secure user authentication and authorization
- 🌐 Network Management - Upload, organize, and manage biological networks
- 📁 Folder Organization - Hierarchical organization of networks and data
- 🔍 Advanced Search - Search networks and users across the platform
- 🎨 Modern UI - Responsive design with dark/light theme support
- 📊 Dynamic Content - Configurable home page content from external sources
- 🚀 Performance Optimized - Built with Next.js App Router for optimal performance
NDEx3 features a dynamic content configuration system that allows updating home page content without code deployments:
- Remote Configuration: Content fetched from external JSON files
- Direct Browser Fetching: No server-side proxies needed
- Four Content Types: Featured content carousel, featured networks, blog content, and logo carousel
- Error Handling: Comprehensive fallback states for content loading failures
See CONTENT_SYSTEM_README.md and CONTENT_CONFIGURATION.md for detailed documentation.
- Node.js 18+
- npm, yarn, pnpm, or bun
-
Clone the repository
git clone https://github.com/ndexbio/ndex3.git cd ndex3 -
Install dependencies
npm install
-
Configure the application
Copy and customize the configuration:
cp public/config-example-root.json public/config.json
Edit
public/config.jsonwith your settings:{ "ndexBaseUrl": "your-ndex-server.com", "keycloakConfig": { "url": "https://your-keycloak-server/auth", "clientId": "your-client-id", "realm": "your-realm" }, "uiContent": { "contentRootPath": "https://your-content-server.com/content/v1", "featuredContent": "featured_content.json", "featuredNetwork": "featured_networks.json", "mainContent": "main.json", "logos": "logos.json" } } -
Run the development server
npm run dev
-
Open your browser
Navigate to http://localhost:3000
NDEx3 follows a modern Next.js App Router architecture with a focus on feature-based colocation, server components, and static export compatibility.
public/ # Static assets and configuration
├── config.json # Application configuration
└── config-example-root.json # Configuration template
src/
├── app/ # Next.js App Router
│ ├── layout.tsx # Root layout with providers
│ ├── page.tsx # Root page (home + client-side routing)
│ ├── loading.tsx # Global loading UI
│ ├── error.tsx # Global error boundary
│ │
│ ├── _components/ # Home page components (feature-based)
│ │
│ ├── search/ # Search feature
│ │ ├── page.tsx
│ │ ├── loading.tsx
│ │ ├── error.tsx
│ │ └── _components/ # Search-specific components
│ │
│ ├── my-account/ # Account management feature
│ │ ├── page.tsx
│ │ ├── loading.tsx
│ │ ├── error.tsx
│ │ └── _components/ # Account-specific components
│ │
│ ├── folders/[uuid]/ # Dynamic folder feature
│ │ ├── page.tsx
│ │ ├── loading.tsx
│ │ └── error.tsx
│ │
│ └── (other features...)
│
├── components/ # Shared React components
│ ├── ui/ # Base UI components (shadcn/ui)
│ ├── SearchBox.tsx # Example shared component
│ └── UserAvatar.tsx # Example shared component
│
├── hooks/ # Custom React hooks (e.g., use-network-search)
│
├── lib/ # Utilities, API clients, and contexts
│ ├── api/ # API clients (NDEx, content service)
│ ├── contexts/ # React contexts (Config, Keycloak)
│ └── utils/ # Utility functions
│
├── stores/ # State management (Zustand)
│
└── types/ # TypeScript type definitions
- Feature-Based Colocation: Components are located with the features that use them (
src/app/[feature]/_components/), improving maintainability. - Shared Components: Truly shared components reside in
src/components/. - Hybrid Routing: Due to
output: 'export'for static deployment, the app uses a hybrid routing strategy:- File-System Routing: For all static routes (
/search,/my-account). - Client-Side Routing: The root
page.tsxhandles dynamic routes with unlimited UUIDs (/folders/[uuid]) that cannot be pre-generated.
- File-System Routing: For all static routes (
- Loading & Error Boundaries: Each route has its own
loading.tsxanderror.tsxfor a resilient and user-friendly experience, leveraging React Suspense and Error Boundaries automatically. - Static Export: The application is optimized for static hosting, with
output: 'export'configured innext.config.ts.
For how this is served and why, see docs/APACHE_STATIC_DEPLOYMENT.md; for URLs that match no route, docs/not-found-routing.md; for the NDEx2 URL rules, docs/legacy-redirects.md.
The main configuration file defines:
- ndexBaseUrl: NDEx server URL
- keycloakConfig: Authentication server settings
- uiContent: Dynamic content configuration
- urlBaseName: Optional URL base path
- cytoscapeWebUrl: Optional Cytoscape Web URL for the "Open in Cytoscape Web" action
- maxNetworkElementsThreshold / maxEdgeCountThreshold: Optional size limits above which "Open in Cytoscape Web" is disabled
- swaggerBaseName: Optional path to the server's Swagger UI
- metricsUrl: Optional base URL for client-side metrics events, such as reporting an unrecognized URL (see docs/not-found-routing.md)
Every field and its default is documented on the AppConfig interface in
src/types/entities/AppConfig.ts.
Content is fetched from external JSON files defined in the uiContent configuration:
- contentRootPath: Base URL for all content files
- Content files:
featured_content.json,featured_networks.json,main.json,logos.json
Build and export the application for static hosting:
npm run buildThe exported files will be in the out/ directory.
run tar czf ndex3.tar.gz -s '/^out/ndex3/' out to create a single tarball that can be uncompressed on deployment server from the parent directory that should contain the entire 'ndex3' webapp distro.
For Apache deployments, see docs/APACHE_STATIC_DEPLOYMENT.md for detailed configuration instructions.
- Next.js 15 - React framework with App Router
- TypeScript - Type-safe development
- Tailwind CSS - Utility-first CSS framework
- shadcn/ui - Modern UI component library
- SWR - Data fetching with caching
- Keycloak - Authentication and authorization
- Zustand - Lightweight state management
npm run dev- Start development servernpm run build- Build for productionnpm run start- Start production servernpm run lint- Run ESLintnpm run type-check- Run TypeScript checks
NDEx3 uses Keycloak for authentication. Configure your Keycloak server details in the keycloakConfig section of public/config.json.
In order to enable Google Analytics, export NEXT_PUBLIC_GA_ID=GS-XXXXX (the analytics ID) prior to running the build.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Start at docs/README.md — the documentation index, which
lists every feature, decision and deployment document and is kept current.
docs/CONFIG_SYSTEM.md- Configuration systemdocs/APACHE_STATIC_DEPLOYMENT.md- Apache deployment guidedocs/CONTENT_SYSTEM_README.md- Content system overviewdocs/CONTENT_CONFIGURATION.md- Detailed content configuration
This project is licensed under the MIT License - see the LICENSE file for details.
For support and questions, please contact the NDEx team or create an issue in the GitHub repository.